@xelth/eck-snapshot 5.4.2 → 5.5.0

package/README.md

@@ -1,11 +1,20 @@
 # eck-snapshot
 
-A CLI tool that packs your entire Git repository into a single text file optimized for LLMs (Claude, Gemini, ChatGPT). Give any AI full project context in one copy-paste.
+A CLI tool that packs your entire Git repository into a single text file optimized for LLMs. Give any AI full project context in one copy-paste.
 
 ```bash
 npm install -g @xelth/eck-snapshot
 ```
 
+## Recommended AI Setup
+
+For best results, we recommend splitting roles between models:
+
+- **Architect** (large context window): Gemini, Grok Fast, ChatGPT — upload the full snapshot, design the architecture, plan tasks
+- **Coder** (execution): Claude (via Claude Code), GLM (via OpenCode) — receive tasks from the architect, write and fix code
+
+eck-snapshot generates tailored instructions (`CLAUDE.md`, `AGENTS.md`) for each role automatically.
+
 ## Core Workflow
 
 ### 1. Full Snapshot
@@ -17,7 +26,7 @@ eck-snapshot
 # -> .eck/snapshots/eckMyProject_26-02-15_12-00_abc1234.md
 ```
 
-That's it. Upload the file to your AI and start working.
+Upload the file to your architect AI and start working.
 
 ### 2. Incremental Update
 
@@ -30,14 +39,6 @@ eck-snapshot update
 
 This uses a Git anchor (saved automatically during full snapshot) to detect all modified files and includes their full content. No redundant diffs, no wasted tokens.
 
-### 3. Lazy Loading
-
-If the AI asks to see specific files that weren't in the snapshot, show them instantly:
-
-```bash
-eck-snapshot show src/auth.rs src/handlers/sync.rs
-```
-
 ## Context Profiles
 
 Large repositories waste tokens on irrelevant code. Profiles let you partition the codebase so the AI only sees what matters.
@@ -103,7 +104,7 @@ eck-snapshot setup-mcp --both    # Setup for Claude Code + OpenCode
 
 This gives your AI access to specialized workers: `glm_zai_frontend`, `glm_zai_backend`, `glm_zai_qa`, `glm_zai_refactor`, and the `eck_finish_task` commit tool.
 
-## Skeleton Mode
+## Skeleton Mode & Lazy Loading
 
 For extremely large projects, skeleton mode strips function bodies and keeps only signatures, types, and structure:
 
@@ -111,6 +112,12 @@ For extremely large projects, skeleton mode strips function bodies and keeps onl
 eck-snapshot --skeleton
 ```
 
+When using skeleton mode, the AI can request full content of specific files on demand:
+
+```bash
+eck-snapshot show src/auth.rs src/handlers/sync.rs
+```
+
 Useful for initial orientation in massive codebases, but full snapshots with profiles are usually more practical.
 
 ## Other Commands

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xelth/eck-snapshot",
-  "version": "5.4.2",
+  "version": "5.5.0",
   "description": "A powerful CLI tool to create and restore single-file text snapshots of Git repositories and directories. Optimized for AI context and LLM workflows.",
   "main": "index.js",
   "type": "module",

package/scripts/mcp-eck-core.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 /**
- * MCP Eck Core - Provides core project management capabilities to Claude
+ * MCP Eck Core - Unified task completion tool for Claude Code and OpenCode
  */
 
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { execa } from "execa";
+import fs from "fs/promises";
 import path from "path";
 import { fileURLToPath } from 'url';
 
@@ -15,7 +16,7 @@ const __dirname = path.dirname(__filename);
 const PROJECT_ROOT = path.resolve(__dirname, '..');
 
 const server = new Server(
-  { name: "eck-core", version: "1.0.0" },
+  { name: "eck-core", version: "2.0.0" },
   { capabilities: { tools: {} } }
 );
 
@@ -24,16 +25,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     tools: [
       {
         name: "eck_finish_task",
-        description: "Completes the current coding task. 1) Stages all changes. 2) Commits with the provided message. 3) Automatically updates the context snapshot. Use this instead of manual git commands.",
+        description: "Completes the current coding task. 1) Overwrites AnswerToSA.md with status for the Architect. 2) Stages all changes. 3) Commits with the provided message. 4) Automatically updates the context snapshot. Use this instead of manual git commands.",
         inputSchema: {
           type: "object",
           properties: {
+            status: {
+              type: "string",
+              description: "Status update for the Architect: what was done, what issues remain, what needs review"
+            },
             message: {
               type: "string",
               description: "Git commit message (follow Conventional Commits, e.g. 'feat: add login')"
             }
           },
-          required: ["message"]
+          required: ["status", "message"]
         }
       }
     ]
@@ -42,20 +47,28 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   if (request.params.name === "eck_finish_task") {
-    const { message } = request.params.arguments;
+    const { status, message } = request.params.arguments;
+    const workDir = process.cwd();
 
     try {
-      // 1. Git Add
-      await execa("git", ["add", "."], { cwd: process.cwd(), timeout: 30000 });
+      // 1. Write fresh AnswerToSA.md (OVERWRITE, not append)
+      const answerDir = path.join(workDir, '.eck', 'lastsnapshot');
+      await fs.mkdir(answerDir, { recursive: true });
+      await fs.writeFile(
+        path.join(answerDir, 'AnswerToSA.md'),
+        `# Agent Report\n\n${status}\n`,
+        'utf-8'
+      );
+
+      // 2. Git Add
+      await execa("git", ["add", "."], { cwd: workDir, timeout: 30000 });
 
-      // 2. Git Commit
-      // We allow empty commits just in case, though unlikely in a finish_task scenario
-      await execa("git", ["commit", "--allow-empty", "-m", message], { cwd: process.cwd(), timeout: 30000 });
+      // 3. Git Commit
+      await execa("git", ["commit", "--allow-empty", "-m", message], { cwd: workDir, timeout: 30000 });
 
-      // 3. Auto Update Snapshot via CLI
-      // We use the local index.js to ensure we use the current version of the tool
+      // 4. Auto Update Snapshot
       const cliPath = path.join(PROJECT_ROOT, "index.js");
-      const { stdout } = await execa("node", [cliPath, "update-auto"], { cwd: process.cwd(), timeout: 120000 });
+      const { stdout } = await execa("node", [cliPath, "update-auto"], { cwd: workDir, timeout: 120000 });
 
       let result;
       try {
@@ -70,22 +83,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return {
           content: [{
             type: "text",
-            text: `✅ Task Completed Successfully.\n\n1. 💾 Git Commit: "${message}"\n2. 📸 Context Updated: ${result.snapshot_file} (+${result.files_count} files)\n\nReady for next instruction.`
+            text: `✅ Committed: "${message}"\n📝 AnswerToSA.md updated\n📸 Snapshot: ${result.snapshot_file} (${result.files_count} files)`
           }]
         };
-      } else if (result.status === "no_changes") {
-        return {
-          content: [{ type: "text", text: `✅ Committed: "${message}"\nℹ️ No new changes for snapshot update.` }]
-        };
       } else {
         return {
-          content: [{ type: "text", text: `✅ Committed: "${message}"\n❌ Snapshot Update Failed: ${result.message}` }]
+          content: [{ type: "text", text: `✅ Committed: "${message}"\nℹ️ Snapshot: ${result.message}` }]
         };
       }
 
     } catch (error) {
       return {
-        content: [{ type: "text", text: `❌ Error finishing task: ${error.message}\n${error.stdout || ''}\n${error.stderr || ''}` }],
+        content: [{ type: "text", text: `❌ Error: ${error.message}\n${error.stderr || ''}` }],
         isError: true
       };
     }

package/src/cli/commands/updateSnapshot.js

@@ -17,15 +17,19 @@ async function generateSnapshotContent(repoPath, changedFiles, anchor, config, g
   let includedCount = 0;
   const fileList = [];
 
-  // Check for Agent Report in .eck/lastsnapshot/AnswerToSA.md (STRICT LOCATION)
-  const reportPath = path.join(repoPath, '.eck', 'lastsnapshot', 'AnswerToSA.md');
+  // Include Agent Report ONLY if it was modified in this commit cycle
+  const reportRelPath = '.eck/lastsnapshot/AnswerToSA.md';
+  const reportChanged = changedFiles.some(f =>
+    f === reportRelPath || f === reportRelPath.replace(/\//g, path.sep)
+  );
+
   let agentReport = null;
-  try {
-    agentReport = await fs.readFile(reportPath, 'utf-8');
-    if (!changedFiles.includes('.eck/lastsnapshot/AnswerToSA.md')) {
-      changedFiles.push('.eck/lastsnapshot/AnswerToSA.md');
-    }
-  } catch (e) { /* No report */ }
+  if (reportChanged) {
+    try {
+      const reportPath = path.join(repoPath, '.eck', 'lastsnapshot', 'AnswerToSA.md');
+      agentReport = await fs.readFile(reportPath, 'utf-8');
+    } catch (e) { /* Failed to read */ }
+  }
 
   for (const filePath of changedFiles) {
     if (config.dirsToIgnore?.some(d => filePath.startsWith(d))) continue;

package/src/mcp-server/index.js

@@ -56,14 +56,14 @@ class EckSnapshotMCPServer {
             properties: {
               status: {
                 type: 'string',
-                description: 'Status update message for AnswerToSA.md (e.g., "Fixed bug X", "Implemented feature Y")',
+                description: 'Status update for the Architect: what was done, what issues remain, what needs review',
               },
-              commitMessage: {
+              message: {
                 type: 'string',
-                description: 'Git commit message. Should follow conventional commits format (e.g., "feat: add user authentication", "fix: resolve login issue")',
+                description: 'Git commit message (follow Conventional Commits, e.g. "feat: add login")',
               },
             },
-            required: ['status', 'commitMessage'],
+            required: ['status', 'message'],
           },
         },
       ],
@@ -75,10 +75,12 @@ class EckSnapshotMCPServer {
         throw new Error(`Unknown tool: ${request.params.name}`);
       }
 
-      const { status, commitMessage } = request.params.arguments;
+      const { status, message } = request.params.arguments;
+      // Support legacy 'commitMessage' parameter
+      const commitMessage = message || request.params.arguments.commitMessage;
 
       if (!status || !commitMessage) {
-        throw new Error('Missing required arguments: status and commitMessage are required');
+        throw new Error('Missing required arguments: status and message are required');
       }
 
       try {
@@ -111,23 +113,11 @@ class EckSnapshotMCPServer {
 
     const steps = [];
 
-    // Step 1: Update AnswerToSA.md
+    // Step 1: Write AnswerToSA.md (OVERWRITE, not append)
     try {
-      const timestamp = new Date().toISOString();
-      const updateContent = `\n## Update - ${timestamp}\n\n${status}\n`;
-
-      // Check if file exists
-      try {
-        await fs.access(answerFilePath);
-        // Append to existing file
-        await fs.appendFile(answerFilePath, updateContent);
-        steps.push({ step: 'update_answer', success: true, message: 'Updated AnswerToSA.md' });
-      } catch {
-        // Create directory and file if not exists
-        await fs.mkdir(path.dirname(answerFilePath), { recursive: true });
-        await fs.writeFile(answerFilePath, `# Task Status\n${updateContent}`);
-        steps.push({ step: 'update_answer', success: true, message: 'Created AnswerToSA.md' });
-      }
+      await fs.mkdir(path.dirname(answerFilePath), { recursive: true });
+      await fs.writeFile(answerFilePath, `# Agent Report\n\n${status}\n`, 'utf-8');
+      steps.push({ step: 'update_answer', success: true, message: 'Updated AnswerToSA.md' });
     } catch (error) {
       steps.push({ step: 'update_answer', success: false, error: error.message });
       throw new Error(`Failed to update AnswerToSA.md: ${error.message}`);