@xelth/eck-snapshot 4.2.4 → 5.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dmytro Surovtsev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+
+# eckSnapshot (v5.4.0)
+
+A specialized CLI tool designed to create and restore single-file text snapshots of Git repositories. It is specifically optimized for providing full project context to Large Language Models (LLMs) like Claude, Gemini, and OpenCode.
+
+🎉 **WE ARE BACK ON NPM!** Version 5.4.0 and onwards are officially available via the npm registry.
+
+## 🚀 Quick Start
+
+```bash
+# Install globally via npm
+npm install -g @xelth/eck-snapshot
+
+# Create a snapshot of your current project
+eck-snapshot
+```
+
+## ✨ Core Features
+
+- **Skeleton Mode:** Strips function bodies using Tree-sitter and Babel to save massive amounts of context tokens.
+- **Delta Updates:** Tracks changes via Git anchors and generates incremental snapshots (`eck-snapshot update`).
+- **Royal Court Architecture:** Multi-agent protocol with dedicated modes for Claude Sonnet (JAS), Claude Opus (JAO), and Gemini (JAG).
+- **GLM Z.AI Worker Fleet:** Built-in MCP server integration for delegating heavy coding tasks to specialized AI workers.
+- **Security:** Built-in `SecretScanner` automatically redacts API keys and sensitive credentials before they hit the LLM context.
+- **Context Profiles:** Smart filtering using auto-detected or manual profiles (e.g., `--profile backend`).
+
+---
+
+## 🛠️ The Core Workflow
+
+### 1. Initial Context (Maximum Compression)
+Create a lightweight map of your entire project. Bodies of functions are hidden, allowing huge monoliths to fit into the AI's context window.
+```bash
+eck-snapshot --skeleton
+# -> Generates: .eck/snapshots/eck[Name]_[Hash]_sk.md
+```
+
+### 2. Lazy Loading (On-Demand Details)
+If the AI needs to see the exact implementation of specific files, it can request them on demand.
+```bash
+eck-snapshot show src/auth.js src/utils/hash.js
+```
+
+### 3. Incremental Updates (Delta)
+As you apply changes, the AI loses context. Instead of re-sending the full repository, send only what changed since the last snapshot!
+```bash
+eck-snapshot update
+# -> Generates an update snapshot with git diffs and modified files
+```
+
+---
+
+## 👑 Royal Court Architecture & GLM Z.AI
+
+`eck-snapshot` is designed to orchestrate a hierarchy of AI agents:
+
+- **Senior Architect:** (You / Gemini / ChatGPT) - Directs the high-level strategy.
+- **Junior Architects:**
+  - `JAS` (Sonnet 4.5): Fast manager for standard features. Run `eck-snapshot --jas`.
+  - `JAO` (Opus 4.5): Deep thinker for critical architecture. Run `eck-snapshot --jao`.
+  - `JAG` (Gemini 3 Pro): Massive context handler. Run `eck-snapshot --jag`.
+
+### MCP Server Integration
+Delegate heavy coding tasks (>100 lines) to the **GLM Z.AI Worker Fleet** to save expensive context window tokens.
+
+1. Get your API key from [Z.AI](https://z.ai) and export it: `export ZAI_API_KEY="your-key-here"`
+2. Setup the MCP servers for Claude Code or OpenCode:
+   ```bash
+   eck-snapshot setup-mcp --both
+   ```
+3. Your AI will now have access to specialized tools: `glm_zai_frontend`, `glm_zai_backend`, `glm_zai_qa`, `glm_zai_refactor`, and the `eck_finish_task` commit tool.
+
+---
+
+## 🧩 Context Profiles
+
+If your repository is huge, you can partition it using Context Profiles:
+
+```bash
+# Auto-detect profiles using AI
+eck-snapshot profile-detect
+
+# List available profiles
+eck-snapshot --profile
+
+# Use a specific profile
+eck-snapshot --profile backend
+
+# Ad-hoc inclusion/exclusion
+eck-snapshot --profile "src/**/*.js,-**/*.test.js"
+```
+
+## 🔐 Environment Syncing
+
+Securely share your `.eck/` configuration (profiles, roadmap, AI instructions) between machines without committing them to the public git history:
+
+```bash
+# Encrypt and pack .eck/ config files
+eck-snapshot env push
+
+# Decrypt and restore on another machine
+eck-snapshot env pull
+```
+
+## License
+MIT License

package/index.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+import dotenv from 'dotenv';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const envPath = path.join(__dirname, '.env');
+dotenv.config({ path: envPath });
+
+const { run } = await import('./src/cli/cli.js');
+run();

package/package.json

@@ -1,9 +1,64 @@
-{
-  "name": "@xelth/eck-snapshot",
-  "version": "4.2.4",
-  "description": "Deprecated. Package removed.",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo deprecated"
-  }
-}
+{
+  "name": "@xelth/eck-snapshot",
+  "version": "5.4.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",
+  "bin": {
+    "eck-snapshot": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE",
+    "src/",
+    "scripts/",
+    "setup.json"
+  ],
+  "scripts": {
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:run": "vitest run"
+  },
+  "author": "xelth-com",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xelth-com/eckSnapshot.git"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.33.1",
+    "@modelcontextprotocol/sdk": "^1.0.1",
+    "@babel/generator": "^7.25.6",
+    "@babel/parser": "^7.25.6",
+    "@babel/traverse": "^7.25.6",
+    "chalk": "^5.3.0",
+    "cli-progress": "^3.12.0",
+    "commander": "^12.1.0",
+    "dotenv": "^16.6.1",
+    "execa": "^8.0.1",
+    "ignore": "^5.3.1",
+    "inquirer": "^9.2.20",
+    "is-binary-path": "^2.1.0",
+    "js-yaml": "^4.1.0",
+    "micromatch": "^4.0.8",
+    "minimatch": "^9.0.3",
+    "ora": "^8.1.0",
+    "p-limit": "^5.0.0",
+    "p-retry": "^6.2.1",
+    "which": "^4.0.0"
+  },
+  "optionalDependencies": {
+    "tree-sitter": "^0.25.0",
+    "tree-sitter-c": "^0.24.1",
+    "tree-sitter-go": "^0.23.4",
+    "tree-sitter-java": "^0.23.5",
+    "tree-sitter-kotlin": "^0.3.8",
+    "tree-sitter-python": "^0.25.0",
+    "tree-sitter-rust": "^0.23.2"
+  },
+  "devDependencies": {
+    "jsdom": "^24.0.0",
+    "vitest": "^2.0.0"
+  }
+}

package/scripts/mcp-eck-core.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * MCP Eck Core - Provides core project management capabilities to Claude
+ */
+
+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 path from "path";
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PROJECT_ROOT = path.resolve(__dirname, '..');
+
+const server = new Server(
+  { name: "eck-core", version: "1.0.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    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.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            message: {
+              type: "string",
+              description: "Git commit message (follow Conventional Commits, e.g. 'feat: add login')"
+            }
+          },
+          required: ["message"]
+        }
+      }
+    ]
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name === "eck_finish_task") {
+    const { message } = request.params.arguments;
+
+    try {
+      // 1. Git Add
+      await execa("git", ["add", "."], { cwd: process.cwd(), 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. Auto Update Snapshot via CLI
+      // We use the local index.js to ensure we use the current version of the tool
+      const cliPath = path.join(PROJECT_ROOT, "index.js");
+      const { stdout } = await execa("node", [cliPath, "update-auto"], { cwd: process.cwd(), timeout: 120000 });
+
+      let result;
+      try {
+        result = JSON.parse(stdout);
+      } catch (e) {
+        return {
+          content: [{ type: "text", text: `✅ Committed: "${message}"\n⚠️ Snapshot update returned invalid JSON: ${stdout}` }]
+        };
+      }
+
+      if (result.status === "success") {
+        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.`
+          }]
+        };
+      } 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}` }]
+        };
+      }
+
+    } catch (error) {
+      return {
+        content: [{ type: "text", text: `❌ Error finishing task: ${error.message}\n${error.stdout || ''}\n${error.stderr || ''}` }],
+        isError: true
+      };
+    }
+  }
+
+  return {
+    content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }],
+    isError: true
+  };
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/scripts/mcp-glm-zai-worker.mjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+/**
+ * MCP GLM Z.AI Worker - Provides specialized worker agents via GLM-4.7 (Z.AI Coding Plan)
+ * Replacement for MiniMax M2.1 worker. Used by Claude Code (Sonnet/Opus) to delegate
+ * heavy coding tasks and save tokens.
+ *
+ * Setup (Claude Code):
+ *   claude mcp add glm-zai -- node scripts/mcp-glm-zai-worker.mjs
+ *
+ * Setup (OpenCode):
+ *   Add to opencode MCP config with the same command path.
+ *
+ * Environment:
+ *   ZAI_API_KEY or ANTHROPIC_AUTH_TOKEN must be set.
+ */
+
+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 Anthropic from "@anthropic-ai/sdk";
+import pRetry from "p-retry";
+import fs from "fs/promises";
+import path from "path";
+
+const API_KEY = process.env.ZAI_API_KEY || process.env.ANTHROPIC_AUTH_TOKEN;
+
+if (!API_KEY) {
+  console.error("ERROR: ZAI_API_KEY (or ANTHROPIC_AUTH_TOKEN) environment variable is not set");
+  console.error("Get your key at https://z.ai and export ZAI_API_KEY=your-key");
+  process.exit(1);
+}
+
+const glmClient = new Anthropic({
+  apiKey: API_KEY,
+  baseURL: "https://api.z.ai/api/anthropic",
+});
+
+// Define Personas - specialized worker roles
+const PERSONAS = {
+  frontend: `You are an Expert Frontend Developer (GLM-4.7).
+Focus: React, Vue, Svelte, Tailwind, CSS, UI/UX, responsive design.
+Goal: Implement the requested UI component, page, or frontend logic.
+Rules:
+- Return ONLY the code or diffs. No explanations unless critical.
+- Follow the existing project conventions you see in the provided files.
+- Use modern ES modules syntax.
+- Ensure accessibility basics (semantic HTML, ARIA where needed).`,
+
+  backend: `You are a Senior Backend Engineer (GLM-4.7).
+Focus: Node.js, Python, Go, SQL, API design, Auth, WebSocket.
+Goal: Implement robust business logic, API endpoints, and data handling.
+Rules:
+- Return ONLY the code or diffs. No explanations unless critical.
+- Follow RESTful principles and existing project patterns.
+- Include proper error handling.
+- Write secure code (no SQL injection, XSS, etc).`,
+
+  qa: `You are a QA Automation Engineer (GLM-4.7).
+Focus: Unit tests, Integration tests, E2E tests, Edge cases.
+Goal: Write comprehensive tests for the provided code.
+Rules:
+- Return ONLY the test files. No explanations unless critical.
+- Use the testing framework already in the project (Jest, Vitest, pytest, etc).
+- Use AAA pattern (Arrange, Act, Assert).
+- Cover happy paths, edge cases, and error scenarios.
+- Aim for >80% coverage of the provided code.`,
+
+  refactor: `You are a Code Quality Specialist (GLM-4.7).
+Focus: Clean Code, DRY, SOLID, Performance optimization, readability.
+Goal: Refactor the provided code to be cleaner, faster, and more maintainable.
+Rules:
+- Return ONLY the refactored code. No explanations unless critical.
+- Preserve existing functionality (no behavior changes).
+- Reduce complexity and duplication.
+- Improve naming and structure.`,
+
+  general: `You are an Expert Full-Stack Developer (GLM-4.7).
+Focus: Full-stack web development, problem-solving, debugging.
+Goal: Complete the requested task efficiently and correctly.
+Rules:
+- Return ONLY the code or diffs. No explanations unless critical.
+- Follow existing project conventions.
+- Write clean, maintainable code.
+- Consider edge cases.`
+};
+
+const server = new Server(
+  { name: "glm-zai-worker", version: "2.0.0" },
+  { capabilities: { tools: {} } }
+);
+
+// 1. Register Tools Dynamically
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  const tools = Object.keys(PERSONAS).map((role) => ({
+    name: `glm_zai_${role}`,
+    description: `Delegate task to GLM Z.AI ${role.toUpperCase()} Specialist (GLM-4.7). Cost-effective worker for heavy coding tasks.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        instruction: {
+          type: "string",
+          description:
+            "Detailed technical instruction for the worker. Be specific about what to implement/change.",
+        },
+        file_paths: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "List of files the worker needs to read as context (paths relative to project root).",
+        },
+        context_summary: {
+          type: "string",
+          description:
+            "Brief context about the project and what we are building (optional but recommended).",
+        },
+      },
+      required: ["instruction"],
+    },
+  }));
+
+  return { tools };
+});
+
+// 2. Handle Tool Calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const toolName = request.params.name;
+
+  if (!toolName.startsWith("glm_zai_")) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Unknown tool: ${toolName}. Available: ${Object.keys(PERSONAS)
+            .map((p) => `glm_zai_${p}`)
+            .join(", ")}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  const role = toolName.replace("glm_zai_", "");
+  const {
+    instruction,
+    file_paths = [],
+    context_summary = "",
+  } = request.params.arguments;
+
+  try {
+    // Read files internally to avoid sending file content through the supervisor
+    let heavyContext = "";
+    const missingFiles = [];
+
+    for (const filePath of file_paths) {
+      try {
+        const absolutePath = path.resolve(process.cwd(), filePath);
+        const content = await fs.readFile(absolutePath, "utf-8");
+        heavyContext += `\n=== FILE: ${filePath} ===\n${content}\n=== END FILE ===\n`;
+      } catch (e) {
+        missingFiles.push(`${filePath} (${e.code || e.message})`);
+      }
+    }
+
+    if (missingFiles.length > 0 && file_paths.length > 0 && missingFiles.length === file_paths.length) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: Could not read any files: ${missingFiles.join(", ")}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    const systemPrompt = PERSONAS[role] || PERSONAS.general;
+
+    let userMessage = "";
+    if (context_summary) {
+      userMessage += `PROJECT CONTEXT: ${context_summary}\n\n`;
+    }
+    userMessage += `TASK: ${instruction}\n`;
+    if (missingFiles.length > 0) {
+      userMessage += `\nWARNING: Could not read some files: ${missingFiles.join(", ")}\n`;
+    }
+    if (heavyContext) {
+      userMessage += `\nSOURCE FILES:\n${heavyContext}`;
+    }
+
+    const response = await pRetry(
+      () => glmClient.messages.create({
+        model: "GLM-4.7",
+        max_tokens: 16384,
+        system: systemPrompt,
+        messages: [{ role: "user", content: userMessage }],
+      }),
+      {
+        retries: 2,
+        onFailedAttempt: (error) => {
+          // Don't retry auth errors or invalid requests
+          if (error.status === 401 || error.status === 400 || error.status === 403) {
+            throw error;
+          }
+        },
+      }
+    );
+
+    let resultText = "";
+    if (response.content && Array.isArray(response.content)) {
+      resultText = response.content
+        .filter((block) => block.type === "text")
+        .map((b) => b.text)
+        .join("\n\n");
+    } else {
+      resultText = "No content returned from GLM Z.AI.";
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `## GLM Z.AI (${role.toUpperCase()}) Output\n\n${resultText}`,
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `GLM Z.AI API Error: ${error.message}\n\nEnsure ZAI_API_KEY is set. Get your key at https://z.ai`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/scripts/verify_changes.js

@@ -0,0 +1,68 @@
+import { execa } from 'execa';
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+console.log('🧪 Starting Verification Suite...');
+
+async function verifySnapshots() {
+  console.log('\n[1/2] Testing Snapshot Logic...');
+  try {
+    // 1. Generate Standard Snapshot
+    await execa('node', ['index.js', 'snapshot', '--no-tree', '--output', 'test_verify_std']);
+    const stdFiles = await fs.readdir('test_verify_std');
+    const stdContent = await fs.readFile(path.join('test_verify_std', stdFiles.find(f => f.endsWith('.md'))), 'utf-8');
+
+    // Extract just the AI instructions header (before the Directory Structure)
+    const stdHeader = stdContent.split('## Directory Structure')[0];
+
+    if (stdHeader.includes('HIERARCHICAL AGENT WORKFLOW')) {
+      throw new Error('❌ Standard snapshot header contains HIERARCHICAL workflow (Should be simple AGENT WORKFLOW!)');
+    }
+    if (!stdHeader.includes('### AGENT WORKFLOW')) {
+      throw new Error('❌ Standard snapshot missing AGENT WORKFLOW section');
+    }
+    console.log('✅ Standard snapshot: OK (Simple AGENT WORKFLOW)');
+
+    // 2. Generate Snapshot with --with-ja flag
+    await execa('node', ['index.js', 'snapshot', '--with-ja', '--no-tree', '--output', 'test_verify_ja']);
+    const jaFiles = await fs.readdir('test_verify_ja');
+
+    // Check the MAIN architect snapshot (not the _ja version)
+    const mainJaFile = jaFiles.find(f => f.endsWith('.md') && !f.includes('_ja.md'));
+    const mainJaContent = await fs.readFile(path.join('test_verify_ja', mainJaFile), 'utf-8');
+
+    // Extract just the AI instructions header for architect snapshot
+    const mainJaHeader = mainJaContent.split('## Directory Structure')[0];
+
+    if (!mainJaHeader.includes('HIERARCHICAL AGENT WORKFLOW')) {
+      throw new Error('❌ Architect snapshot (with --with-ja) missing HIERARCHICAL AGENT WORKFLOW');
+    }
+    if (!mainJaHeader.includes('Junior Architect')) {
+      throw new Error('❌ Architect snapshot (with --with-ja) missing Junior Architect references');
+    }
+    console.log('✅ Architect snapshot (with --with-ja): OK (HIERARCHICAL AGENT WORKFLOW with JA delegation)');
+
+    // Also verify the _ja snapshot uses agent mode
+    const jaAgentFile = jaFiles.find(f => f.includes('_ja.md'));
+    const jaAgentContent = await fs.readFile(path.join('test_verify_ja', jaAgentFile), 'utf-8');
+
+    // Extract just the AI instructions header for JA agent snapshot
+    const jaAgentHeader = jaAgentContent.split('## Directory Structure')[0];
+
+    if (jaAgentHeader.includes('HIERARCHICAL AGENT WORKFLOW')) {
+      throw new Error('❌ JA agent snapshot header should NOT have HIERARCHICAL AGENT WORKFLOW (it uses agent template)');
+    }
+    // Verify it has the agent template marker
+    if (!jaAgentHeader.includes('Project Snapshot Information')) {
+      throw new Error('❌ JA agent snapshot missing agent template marker');
+    }
+    console.log('✅ JA agent snapshot (_ja.md): OK (Uses agent template as expected)');
+
+  } catch (e) {
+    console.error('Snapshot verification failed:', e.message);
+    process.exit(1);
+  }
+}
+
+verifySnapshots();