@xelth/eck-snapshot 5.8.6 → 6.0.0

package/README.md

@@ -1,190 +1,71 @@
-# eck-snapshot
+# 📸 eckSnapshot v6.0
 
-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.
+A specialized, AI-native CLI tool designed to create and restore single-file text snapshots of Git repositories. Optimized for providing full project context to Large Language Models (LLMs) and serving as the coordination hub for Multi-Agent AI Architectures.
 
-```bash
-npm install -g @xelth/eck-snapshot
-```
-
-## Recommended AI Setup
-
-For best results, we recommend splitting roles between models:
+## 🌟 Key Features
 
-- **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
+* **🧠 Multi-Agent Protocol (Royal Court):** Built-in support for the "Royal Court" architecture. Delegate tasks from a Senior Architect (Claude/Gemini) to Junior Managers, who orchestrate a swarm of specialized GLM-4.7 workers.
+* **☠️ Skeleton Mode:** Uses `Tree-sitter` and `Babel` to strip function bodies, drastically reducing token count while preserving structural context. Supports JS/TS, Rust, Go, Python, C, Java, and Kotlin.
+* **🔄 Smart Delta Updates:** Tracks incremental changes via Git anchors with sequential numbering. Now accurately tracks and reports deleted files to prevent LLM hallucinations.
+* **🛡️ Security (SecretScanner):** Automatically redacts API keys and credentials before sending context to LLMs. Features both Regex matching and **Shannon Entropy** analysis for catching non-standard hardcoded secrets.
+* **📊 Telemetry Hub:** Integrated with a Rust-based microservice (`eck-telemetry`) for tracking agent execution metrics, auto-syncing token estimation weights via linear regression, and in-memory caching.
+* **🔌 Native MCP Integration:** Instantly spins up Model Context Protocol (MCP) servers (`eck-core` for context sync and `glm-zai` for worker swarms) for Claude Code and OpenCode.
 
-eck-snapshot generates tailored instructions (`CLAUDE.md`, `AGENTS.md`) for each role automatically.
-
-## Core Workflow
-
-### 1. Full Snapshot
-
-Run `eck-snapshot` in your project root. It scans every tracked file, filters out noise (lock files, build artifacts, secrets), and produces a single `.md` file ready for an AI chat.
+## 🚀 Quick Start
 
+### Installation
 ```bash
-eck-snapshot
-# -> .eck/snapshots/eckMyProject_26-02-15_12-00_abc1234.md
-```
-
-Upload the file to your architect AI and start working.
-
-### 2. Incremental Update
-
-After you make changes, don't re-send the entire project. Send only what changed since the last full snapshot:
-
-```bash
-eck-snapshot update
-# -> .eck/snapshots/eckMyProject_26-02-15_14-30_abc1234_up1_42kb.md
-```
-
-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.
-
-Notice the `_42kb` suffix in the filename — this is the **Anti-Truncation Guard** (see below).
-
-## Context Profiles
-
-Large repositories waste tokens on irrelevant code. Profiles let you partition the codebase so the AI only sees what matters.
-
-### Auto-Detection
-
-Let AI scan your directory tree and generate profiles automatically:
-
-```bash
-eck-snapshot profile-detect
-# -> Saves profiles to .eck/profiles.json
-```
-
-### Manual Guide
-
-For very large repos where auto-detection is too slow, generate a prompt guide, paste it into a powerful Web LLM (Gemini, ChatGPT), and save the resulting JSON:
-
-```bash
-eck-snapshot generate-profile-guide
-# -> .eck/profile_generation_guide.md (paste into AI, get profiles back)
-```
-
-### Using Profiles
-
-```bash
-eck-snapshot --profile                            # List all available profiles
-eck-snapshot --profile backend                    # Use a named profile
-eck-snapshot --profile backend --skeleton         # Profile + skeleton mode
-eck-snapshot --profile "src/**/*.rs,-**/test_*"   # Ad-hoc glob filtering
-```
-
-Profiles work with both full snapshots and incremental updates.
-
-## Anti-Truncation Guard
-
-Web AI interfaces (Gemini, ChatGPT) sometimes silently drop the content of large uploaded files, replacing them with a small JSON metadata stub like `{"fileName": "...", "contentFetchId": "..."}`. The AI then hallucinates code it never actually received.
-
-eck-snapshot counters this with two mechanisms:
-
-**1. Size-stamped filenames.** Every snapshot — full and incremental — embeds its exact size in kilobytes directly in the filename:
-
-```
-eckMyProject_26-02-15_12-00_abc1234_1250kb.md      ← full snapshot
-eckMyProject_26-02-15_14-30_abc1234_up1_42kb.md    ← incremental update
+npm install -g @xelth/eck-snapshot
 ```
 
-**2. AI instructions baked into the snapshot.** The snapshot header instructs the AI to cross-check the `kb` value in the filename against the actual payload it received. If there is a mismatch, the AI is required to stop and alert you instead of hallucinating:
-
-> 🚨 **System Error:** The web interface truncated the file `eckMyProject_..._1250kb.md`. I only received the metadata/JSON stub, not the actual 1250 kb of code. Please split the snapshot or paste the text directly.
-
-This protection works on any web interface that embeds the filename (Gemini, ChatGPT, Grok, etc.).
-
-## Smart Filtering
-
-eck-snapshot automatically detects your project type (Rust, Node.js, Android, Python, etc.) and excludes language-specific noise:
-
-- **Rust**: `Cargo.lock`, `target/`
-- **Node.js**: `package-lock.json`, `node_modules/`
-- **Android**: build artifacts, generated code
-- **All projects**: `.git/`, IDE configs, binary files
-
-The built-in `SecretScanner` also redacts API keys, tokens, and credentials before they reach the AI.
-
-## Multi-Agent Architecture
-
-eck-snapshot generates tailored `CLAUDE.md` instructions for different AI agent roles:
-
+### Basic Usage
 ```bash
-eck-snapshot --jas    # Junior Architect Sonnet - fast, standard features
-eck-snapshot --jao    # Junior Architect Opus - deep, critical architecture
-eck-snapshot --jag    # Junior Architect Gemini - massive context tasks
-```
-
-### Chinese Delegation (`--zh`)
+# Create a standard full snapshot
+eck-snapshot snapshot
 
-For GLM Z.AI workers (trained on Chinese data), the `--zh` flag instructs the architect to formulate all worker tasks in Chinese, improving output quality:
+# Create a highly compressed skeleton snapshot
+eck-snapshot snapshot --skeleton
 
-```bash
-eck-snapshot --jas --zh    # Claude Code: delegate to GLM workers in Chinese
-eck-snapshot --zh          # OpenCode/GLM: generate AGENTS.md with Chinese protocol
+# Create an incremental update (only changed/deleted files)
+eck-snapshot update
 ```
 
-The architect still communicates with you in your language. Only the `instruction` parameter sent to GLM workers switches to Chinese. Code, variable names, and commit messages stay in English.
+## 🤖 AI Swarm Setup (GLM Z.AI)
 
-### MCP Server Integration
+eckSnapshot v6 acts as the bridge between your primary AI IDE (Claude Code or OpenCode) and a cost-effective GLM-4.7 worker swarm.
 
-Delegate coding tasks to the GLM Z.AI Worker Fleet via MCP:
+1. **Get an API Key:** Register at [Z.AI](https://z.ai) and set `export ZAI_API_KEY="your-key"`.
+2. **Setup MCP Servers:**
+   ```bash
+   eck-snapshot setup-mcp --both
+   ```
+3. **Initialize Project Manifests:**
+   ```bash
+   # Generates smart instructions (CLAUDE.md / AGENTS.md)
+   eck-snapshot snapshot --jas  # For Claude Code (Sonnet 4.5)
+   eck-snapshot snapshot --jaz  # For OpenCode (GLM-4.7)
+   ```
 
-```bash
-export ZAI_API_KEY="your-key"
-eck-snapshot setup-mcp --both    # Setup for Claude Code + OpenCode
-```
+## 📁 The `.eck/` Manifest Directory
 
-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.
+eckSnapshot automatically maintains a `.eck/` directory in your project to provide deep context to AI agents:
+- `CONTEXT.md` - High-level architecture (Auto-generated)
+- `ENVIRONMENT.md` - Runtime specifics (Auto-generated)
+- `ROADMAP.md` & `TECH_DEBT.md` - Strategic planning
+- `RUNTIME_STATE.md` - Live port/process status
 
-## Skeleton Mode & Lazy Loading
+*Note: The tool automatically filters confidential files like `SERVER_ACCESS.md` from snapshots to ensure security.*
 
-For extremely large projects, skeleton mode strips function bodies and keeps only signatures, types, and structure:
+## 📈 Token Estimation
 
+Train the local estimator to perfectly predict token counts for your specific project:
 ```bash
-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
+# Manually push agent telemetry
+eck-snapshot telemetry push
 
-```bash
-eck-snapshot restore <snapshot>    # Restore files from a snapshot to disk
-eck-snapshot prune <snapshot>      # AI-powered snapshot size reduction
-eck-snapshot doctor                # Check project health
-eck-snapshot env push              # Encrypt and sync .eck/ config between machines
-eck-snapshot env pull              # Restore .eck/ config on another machine
+# Sync global token weights from the Telemetry Hub
+eck-snapshot telemetry sync-weights
 ```
 
-## Changelog
-
-### v5.8.6
-- **Anti-Truncation Guard:** Every snapshot filename now includes its size in KB (e.g., `_1250kb.md`). The snapshot header instructs the AI to verify the payload size matches the filename and alert the user if the web UI truncated the file instead of hallucinating missing code.
-- **Incremental snapshot filtering parity:** `eck-snapshot update` now applies the same file guards as full snapshots — hidden paths (`.idea/`, `.vscode/`), binary files, and glob patterns in `filesToIgnore` are all properly filtered out, preventing IDE config files or committed binaries from bloating update snapshots.
-
-### v5.8.5
-- Re-publish to fix missing README on npmjs.com.
-
-### v5.8.4
-- Fixed directory filtering in incremental snapshots. Paths like `web/build/app.js` are now correctly ignored when `build/` is in the ignore list.
-
-### v5.8.3
-- Optimized agent report formatting with clean Markdown to improve token efficiency.
-- Fixed report injection order so it appears correctly after system instructions.
-
-### v5.8.2
-- Fixed agent report injection in incremental snapshots. The `AnswerToSA.md` file is now preserved on disk for manual debugging and uses an internal `[SYSTEM: EMBEDDED]` marker to prevent duplicate injections into future snapshots.
-
-### v5.8.1
-- Improved Android project parsing by ignoring boilerplate and vector graphics.
-- Removed duplicate `ecksnapshot` MCP server and fixed JSON parsing in `update-auto`.
-
 ## License
-
-MIT
+MIT © xelth-com

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xelth/eck-snapshot",
-  "version": "5.8.6",
-  "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.",
+  "version": "6.0.0",
+  "description": "A powerful CLI tool to create and restore single-file text snapshots of Git repositories. Optimized for AI context, LLM workflows, and multi-agent Swarm coordination.",
   "main": "index.js",
   "type": "module",
   "bin": {

package/scripts/mcp-eck-core.js

@@ -24,8 +24,22 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
   return {
     tools: [
       {
-        name: "eck_finish_task",
-        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.",
+        name: "eck_fail_task",
+        description: "Use this if you are stuck, blocked, or unable to complete the task. It saves your report to AnswerToSA.md and generates an emergency snapshot WITHOUT committing broken code. Do NOT use this if tests pass.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            status: {
+              type: "string",
+              description: "Detailed explanation of why you are blocked, what you tried, and what the Architect should know."
+            }
+          },
+          required: ["status"]
+        }
+      },
+      {
+        name: "eck_finish_task",
+        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. WARNING: USE ONLY ONCE PER TASK WHEN 100% FINISHED. Do NOT use this for intermediate saves or testing during your debugging loop.",
         inputSchema: {
           type: "object",
           properties: {
@@ -46,6 +60,40 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 });
 
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name === "eck_fail_task") {
+    const { status } = request.params.arguments;
+    const workDir = process.cwd();
+
+    try {
+      const answerDir = path.join(workDir, '.eck', 'lastsnapshot');
+      await fs.mkdir(answerDir, { recursive: true });
+      await fs.writeFile(
+        path.join(answerDir, 'AnswerToSA.md'),
+        `# Agent Report (BLOCKED/FAILED)\n\n${status}\n`,
+        'utf-8'
+      );
+
+      const cliPath = path.join(PROJECT_ROOT, "index.js");
+      const { stdout } = await execa("node", [cliPath, "update-auto", "--fail"], { cwd: workDir, timeout: 120000 });
+
+      let result;
+      try {
+        result = JSON.parse(stdout);
+      } catch (e) {
+        return { content: [{ type: "text", text: `⚠️ Task aborted, but snapshot update returned invalid JSON: ${stdout}` }] };
+      }
+
+      return {
+        content: [{
+          type: "text",
+          text: `🚨 Task marked as FAILED.\n📝 AnswerToSA.md updated\n📸 Emergency Snapshot: ${result.snapshot_file} (${result.files_count} files)`
+        }]
+      };
+    } catch (error) {
+      return { content: [{ type: "text", text: `❌ Error: ${error.message}\n${error.stderr || ''}` }], isError: true };
+    }
+  }
+
   if (request.params.name === "eck_finish_task") {
     const { status, message } = request.params.arguments;
     const workDir = process.cwd();
@@ -106,14 +154,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   };
 });
 
-const transport = new StdioServerTransport();
-await server.connect(transport);
-
-// --- Graceful Shutdown Handler ---
-process.stdout.on('error', (err) => {
-  if (err.code === 'EPIPE') {
-    process.exit(0);
-  }
-});
-process.on('SIGINT', () => process.exit(0));
-process.on('SIGTERM', () => process.exit(0));
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+// --- Graceful Shutdown Handler ---
+process.stdout.on('error', (err) => {
+  if (err.code === 'EPIPE') {
+    process.exit(0);
+  }
+});
+process.on('SIGINT', () => process.exit(0));
+process.on('SIGTERM', () => process.exit(0));

package/setup.json

@@ -576,66 +576,70 @@
         "capabilities": ["npm", "git", "basic editing"],
         "restrictions": ["Do not use for complex architectural tasks"]
       },
-      "jas": {
-        "active": true,
-        "name": "Junior Architect (Sonnet 4.5)",
-        "description": "Smart & Fast Manager. Best for standard features and refactoring. Manages GLM Z.AI workers.",
-        "guiSupport": true,
-        "identification": {
-          "markers": ["sonnet", "fast_architect"]
-        },
-        "capabilities": [
-          "glm_zai_frontend",
-          "glm_zai_backend",
-          "glm_zai_qa",
-          "glm_zai_refactor",
-          "glm_zai_general",
-          "git operations",
-          "npm run dev"
-        ],
-        "restrictions": [
-          "Prefer delegating heavy coding to GLM Z.AI workers",
-          "Focus on glue code and logic verification"
-        ]
-      },
-      "jao": {
-        "active": true,
-        "name": "Junior Architect (Opus 4.5)",
-        "description": "Deep Thinker & Planner. Expensive. Use for critical architecture, security, and complex logic.",
-        "guiSupport": true,
-        "identification": {
-          "markers": ["opus", "deep_architect"]
-        },
-        "capabilities": [
-          "glm_zai_frontend",
-          "glm_zai_backend",
-          "glm_zai_qa",
-          "glm_zai_refactor",
-          "glm_zai_general",
-          "analysis"
-        ],
-        "restrictions": [
-          "STRICTLY DELEGATE boilerplate to GLM Z.AI",
-          "Verify every line of code generated by workers",
-          "Plan before execution"
-        ]
-      },
-      "jag": {
-        "active": true,
-        "name": "Junior Architect (Gemini 3 Pro)",
-        "description": "Massive Context Handler. Use when changes span >50 files or require full repo understanding.",
-        "guiSupport": false,
-        "identification": {
-          "markers": ["gemini_wsl"]
-        },
-        "capabilities": [
-          "read entire repo",
-          "delegate to claude"
-        ],
-        "restrictions": [
-          "Experimental environment"
-        ]
-      },
+      "jas": {
+        "active": true,
+        "name": "Junior Architect (Sonnet 4.5)",
+        "description": "Project Mode Orchestrator (Claude Code only). Smart & Fast Manager. Manages GLM Z.AI workers for efficient task delegation.",
+        "guiSupport": true,
+        "identification": {
+          "markers": ["sonnet", "fast_architect"]
+        },
+        "capabilities": [
+          "glm_zai_frontend",
+          "glm_zai_backend",
+          "glm_zai_qa",
+          "glm_zai_refactor",
+          "glm_zai_general",
+          "git operations",
+          "npm run dev"
+        ],
+        "restrictions": [
+          "Prefer delegating heavy coding to GLM Z.AI workers",
+          "Focus on glue code and logic verification"
+        ]
+      },
+      "jao": {
+        "active": true,
+        "name": "Junior Architect (Opus 4.5)",
+        "description": "Project Mode Orchestrator (Claude Code only). Deep Thinker & Planner. Expensive. Use for critical architecture, security, and complex logic.",
+        "guiSupport": true,
+        "identification": {
+          "markers": ["opus", "deep_architect"]
+        },
+        "capabilities": [
+          "glm_zai_frontend",
+          "glm_zai_backend",
+          "glm_zai_qa",
+          "glm_zai_refactor",
+          "glm_zai_general",
+          "analysis"
+        ],
+        "restrictions": [
+          "STRICTLY DELEGATE boilerplate to GLM Z.AI",
+          "Verify every line of code generated by workers",
+          "Plan before execution"
+        ]
+      },
+      "jaz": {
+        "active": true,
+        "name": "Junior Architect (GLM-4.7 via OpenCode)",
+        "description": "Project Orchestrator for OpenCode. Highly accessible/budget-friendly. Manages the GLM Z.AI worker swarm.",
+        "guiSupport": true,
+        "identification": {
+          "markers": ["opencode", "glm-4.7"]
+        },
+        "capabilities": [
+          "glm_zai_frontend",
+          "glm_zai_backend",
+          "glm_zai_qa",
+          "glm_zai_refactor",
+          "glm_zai_general",
+          "git operations"
+        ],
+        "restrictions": [
+          "Strictly delegate complex/large logic to workers to preserve context window"
+        ]
+      },
       "production_server": {
         "active": true,
         "name": "Production Server Agent (AGENT_PROD_SERVER)",

package/src/cli/cli.js

@@ -17,6 +17,7 @@ import { executePrompt, executePromptWithSession } from '../services/claudeCliSe
 import { detectProfiles } from './commands/detectProfiles.js';
 import { generateProfileGuide } from './commands/generateProfileGuide.js';
 import { setupGemini } from './commands/setupGemini.js';
+import { pushTelemetry } from '../utils/telemetry.js';
 
 import { showFile } from './commands/showFile.js';
 import { runDoctor } from './commands/doctor.js';
@@ -181,9 +182,9 @@ Option C: Using Profiles
     .option('--enhanced', 'Use enhanced multi-agent headers (default: true)', true)
     .option('--profile [name]', 'Filter files using profiles and/or ad-hoc glob patterns. Run without argument to list available profiles.')
     .option('--agent', 'Generate a snapshot optimized for a command-line agent')
-    .option('--jag', 'Generate snapshot for Junior Architect Gemini (Gemini 3 Pro)')
-    .option('--jas', 'Configure project for Junior Architect Sonnet (Sonnet 4.5)')
-    .option('--jao', 'Configure project for Junior Architect Opus (Opus 4.5)')
+    .option('--jas', 'Enable Project Mode for Junior Architect Sonnet (Claude Code only)')
+    .option('--jao', 'Enable Project Mode for Junior Architect Opus (Claude Code only)')
+    .option('--jaz', 'Enable Project Mode for Junior Architect GLM (OpenCode Z.AI only)')
     .option('--zh', 'Communicate with GLM Z.AI workers in Chinese for better quality')
     .option('--skeleton', 'Enable skeleton mode: strip function bodies to save context window tokens')
     .option('--max-lines-per-file <number>', 'Truncate files to max N lines (e.g., 200 for compact snapshots)', (val) => parseInt(val))
@@ -204,6 +205,7 @@ Quick --profile Examples:
     .description('Create a delta snapshot of changed files since the last full snapshot')
     .argument('[repoPath]', 'Path to the repository', process.cwd())
     .option('--config <path>', 'Configuration file path')
+    .option('-f, --fail', 'Create an emergency snapshot without git commit')
     .action(updateSnapshot);
 
   // Auto/Silent Update command for Agents
@@ -211,6 +213,7 @@ Quick --profile Examples:
     .command('update-auto')
     .description('Silent update for AI agents (JSON output)')
     .argument('[repoPath]', 'Path to the repository', process.cwd())
+    .option('-f, --fail', 'Create an emergency snapshot without git commit')
     .action(updateSnapshotJson);
 
   // Restore command
@@ -403,5 +406,24 @@ Quick --profile Examples:
     .option('-v, --verbose', 'Show detailed output')
     .action(envPull);
 
+  // Telemetry commands
+  const telemetryCmd = program.command('telemetry').description('Manage Telemetry Hub synchronization');
+  telemetryCmd
+    .command('push')
+    .description('Manually push the latest AnswerToSA.md report to xelth.com/T/report')
+    .argument('[repoPath]', 'Path to the repository', process.cwd())
+    .action(async (repoPath) => {
+      console.log(chalk.blue('Pushing agent telemetry...'));
+      await pushTelemetry(repoPath, false);
+    });
+
+  telemetryCmd
+    .command('sync-weights')
+    .description('Fetch the latest global token estimation weights from Telemetry Hub')
+    .action(async () => {
+      const { syncTokenWeights } = await import('../utils/tokenEstimator.js');
+      await syncTokenWeights();
+    });
+
   program.parse(process.argv);
 }