@xelth/eck-snapshot 4.0.0 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xelth/eck-snapshot",
-  "version": "4.0.0",
+  "version": "4.1.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",
@@ -29,6 +29,7 @@
     "url": "https://github.com/xelth-com/eckSnapshot.git"
   },
   "dependencies": {
+    "@babel/generator": "^7.25.6",
     "@babel/parser": "^7.25.6",
     "@babel/traverse": "^7.25.6",
     "chalk": "^5.3.0",
@@ -43,6 +44,11 @@
     "ora": "^8.1.0",
     "p-limit": "^5.0.0",
     "p-retry": "^6.2.1",
+    "tree-sitter": "^0.25.0",
+    "tree-sitter-c": "^0.24.1",
+    "tree-sitter-java": "^0.23.5",
+    "tree-sitter-kotlin": "^0.3.8",
+    "tree-sitter-python": "^0.25.0",
     "which": "^4.0.0"
   },
   "devDependencies": {

package/setup.json

@@ -374,7 +374,6 @@
     "dirsToIgnore": [
       "node_modules/",
       ".git/",
-      ".eck/",
       "dist/",
       "build/",
       ".next/",
@@ -387,6 +386,27 @@
       "create-snapshot/"
     ],
     "includeHidden": false,
+    "eckDirectoryFiltering": {
+      "_comment": "Smart filtering for .eck directory - includes documentation but excludes confidential files",
+      "enabled": true,
+      "confidentialPatterns": [
+        "SERVER_ACCESS.md",
+        "CREDENTIALS*.md",
+        "SECRETS*.md",
+        "*.secret",
+        "*.key",
+        "*.pem",
+        ".env*"
+      ],
+      "alwaysIncludePatterns": [
+        "ARCHITECTURE.md",
+        "CONTEXT.md",
+        "OPERATIONS.md",
+        "ROADMAP.md",
+        "TECH_DEBT.md",
+        "README.md"
+      ]
+    },
     "projectSpecific": {
       "android": {
         "filesToIgnore": [
@@ -539,9 +559,11 @@
         "Request ENV scan from agent",
         "Analyze User Request in their native language",
         "Formulate environment-appropriate technical plan",
-        "Propose the plan and await user confirmation",
-        "Generate environment-specific JSON command block",
-        "Communicate with user in their language, commands in ENGLISH"
+        "Propose the high-level plan in the user's language",
+        "STOP and WAIT for explicit user confirmation",
+        "ONLY after approval: Generate environment-specific JSON command block in a SEPARATE message",
+        "Communicate with user in their language, commands in ENGLISH",
+        "CRITICAL: Never output JSON commands until the user agrees to the plan"
       ]
     },
     "executionAgents": {
@@ -568,7 +590,9 @@
           "electron debug",
           "file editing",
           "testing commands",
-          "browser automation"
+          "browser automation (chrome_mcp)",
+          "visual regression testing",
+          "network logging"
         ],
         "restrictions": [
           "no PM2 commands",
@@ -713,6 +737,24 @@
         ]
       }
     },
+    "browserAutomation": {
+      "enabled": true,
+      "provider": "Claude in Chrome MCP",
+      "availableFor": ["local_dev"],
+      "usage_protocol": "CRITICAL: Browser tasks MUST be executed directly by the interactive 'local_dev' agent using its internal tools. DO NOT delegate browser tasks via the 'eck-snapshot ask-claude' CLI command, as the subprocess lacks MCP context.",
+      "capabilities": {
+        "navigation": "Navigate URLs, handle tabs/windows",
+        "interaction": "Click, type, scroll, drag-and-drop",
+        "inspection": "Read DOM, extract text, verify styles",
+        "debugging": "Access console logs, network activity",
+        "visual": "Generate screenshots, record GIF"
+      },
+      "restrictions": [
+        "No non-consensual file downloads",
+        "No sensitive credentials interaction",
+        "MUST NOT use 'eck-snapshot ask-claude' wrapper for these tasks"
+      ]
+    },
     "header": {
       "defaultEnabled": true,
       "_comment": "Controls whether AI instruction headers are included by default in snapshots"

package/src/cli/cli.js

@@ -7,6 +7,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 import { createRepoSnapshot } from './commands/createSnapshot.js';
+import { updateSnapshot } from './commands/updateSnapshot.js';
 import { restoreSnapshot } from './commands/restoreSnapshot.js';
 import { pruneSnapshot } from './commands/pruneSnapshot.js';
 import { generateConsilium } from './commands/consilium.js';
@@ -19,6 +20,7 @@ import { detectProfiles } from './commands/detectProfiles.js';
 import { generateProfileGuide } from './commands/generateProfileGuide.js';
 import { setupGemini } from './commands/setupGemini.js';
 import { generateAutoDocs } from './commands/autoDocs.js';
+import { showFile } from './commands/showFile.js';
 import inquirer from 'inquirer';
 import ora from 'ora';
 import { execa } from 'execa';
@@ -31,10 +33,10 @@ async function checkCodeBoundaries(filePath, agentId) {
   try {
     const content = await fs.readFile(filePath, 'utf-8');
     const boundaryRegex = /\/\* AGENT_BOUNDARY:\[([^\]]+)\] START \*\/([\s\S]*?)\/\* AGENT_BOUNDARY:\[[^\]]+\] END \*\//g;
-    
+
     const boundaries = [];
     let match;
-    
+
     while ((match = boundaryRegex.exec(content)) !== null) {
       boundaries.push({
         owner: match[1],
@@ -43,7 +45,7 @@ async function checkCodeBoundaries(filePath, agentId) {
         content: match[2]
       });
     }
-    
+
     return {
       file: filePath,
       hasBoundaries: boundaries.length > 0,
@@ -63,89 +65,61 @@ async function checkCodeBoundaries(filePath, agentId) {
 export function run() {
   const program = new Command();
 
-  const helpGuide = `eck-snapshot (v4.0.0) - A lightweight, platform-independent CLI for creating project snapshots.
-
---- Getting Started: Environment Setup ---
-
-This tool is designed to work with Large Language Models (LLMs). For the best results, you'll need:
-1. An 'Architect' LLM (like Gemini, GPT-4, or Grok) to analyze snapshots.
-2. A 'Coder' LLM (like Claude Code) to execute coding tasks.
-
---- Core Workflow: A Step-by-Step Guide ---
-
-Step 1: Create a Full Project Snapshot
-This is your primary command. It scans your project and packs all code into a single file.
-
-> Usage:
-  $ eck-snapshot
-
--> This creates a file like 'myProject_snapshot_... .md' in the .eck/snapshots/ directory.
-   You can now pass this file to your Architect LLM for analysis.
-
-
-Step 2: Handle Large Projects with Auto-Profiling
-If your project is too big for the LLM's context window, \`profile-detect\` will automatically
-slice it into logical parts (profiles) using AI.
-
-> Usage:
-  $ eck-snapshot profile-detect
-
--> Output:
-  ✨ Detected Profiles:
-  ---------------------------
-    - cli
-    - services
-    - core
-    - templates
-    - docs
-    - config
-
-
-Step 3: Use Profiles to Create Focused Snapshots
-Use the --profile option to create smaller snapshots of specific project areas.
-
-> Example 1: Combine and exclude profiles
-  $ eck-snapshot --profile "core,services,cli,-docs,-config"
-
--> Creates a snapshot with code from the 'core', 'services', and 'cli' profiles,
-   while excluding anything from 'docs' and 'config'.
-
-> Example 2: Use ad-hoc glob patterns
-  $ eck-snapshot --profile "src/**/*.js,-**/*.test.js"
-
--> Includes all .js files in the 'src' directory and its subdirectories,
-   but excludes any file ending in '.test.js'.
-   Note: Quotes are required for complex patterns.
-
-
-Step 4: Intelligently Prune a Snapshot
-If a snapshot is still too large, \`prune\` uses AI to shrink it to a target size,
-keeping only the most important files.
-
-> Usage:
-  $ eck-snapshot prune myProject_snapshot.md --target-size 500KB
-
-
-Step 5 (Alternative): Truncate Files by Line Count
-A faster, non-AI method to reduce size by keeping only the top N lines of each file.
-Useful for a high-level overview.
-
-> Usage:
-  $ eck-snapshot --max-lines-per-file 200
-
---- Auxiliary Commands ---
-
-- restore:                  Restore a project from a snapshot file.
-- generate-profile-guide:   Creates a guide for manual profile creation. Use this if 'profile-detect' fails on very large projects, as it allows you to use an LLM with a larger context window (e.g., a web UI).
-- detect:                   Show how eckSnapshot identifies your project type.
-- ask-gpt / ask-claude:     Directly query the configured AI coder agents.
-- setup-gemini:             Auto-configure integration with gemini-cli.
+  const helpGuide = `eck-snapshot (v4.1.0) - AI-Native Repository Context Tool.
+
+--- 🚀 Core Workflow: Optimized for Web LLMs (Gemini/ChatGPT) ---
+
+1. Initial Context (Maximum Compression)
+   Create a lightweight map of your entire project. Bodies of functions are hidden.
+   This fits huge monoliths into the context window.
+   
+   $ eck-snapshot --skeleton
+   -> Generates: .eck/snapshots/<name>_sk.md (Upload this to AI)
+
+2. Lazy Loading (On-Demand Details)
+   If the AI needs to see the implementation of specific files, it will ask you.
+   You can display multiple files at once to copy-paste back to the chat.
+   
+   $ eck-snapshot show src/auth.js src/utils/hash.js
+
+3. Working & Updating
+   As you apply changes, the AI loses context. Instead of re-sending the full repo,
+   send only what changed since the last snapshot.
+   
+   $ eck-snapshot update
+   -> Generates: .eck/snapshots/update_<timestamp>.md (Contains changed files + git diff)
+
+--- 🛠️ Managing Context Profiles ---
+
+Option A: Auto-Detection (Best for start)
+   Uses AI to scan folders and suggest profiles (backend, frontend, etc).
+   $ eck-snapshot profile-detect
+
+Option B: Manual Guide (Best for large repos)
+   If the project is too big for auto-detection, this generates a prompt text file
+   that you can paste into a powerful Web LLM (like Gemini 1.5 Pro) to design profiles manually.
+   
+   1. Run:  $ eck-snapshot generate-profile-guide
+   2. Open: .eck/profile_generation_guide.md
+   3. Copy: Paste the content into your AI chat.
+   4. Save: Take the JSON response and save it to .eck/profiles.json
+
+Option C: Using Profiles
+   $ eck-snapshot --profile backend
+   $ eck-snapshot --profile "frontend,-**/*.test.js" (Ad-hoc filtering)
+
+--- 🧩 Auxiliary Commands ---
+
+- restore:            Restore files from a snapshot to disk.
+- prune:              Use AI to shrink a snapshot file by importance.
+- ask-gpt/claude:     Delegate tasks to agents directly (via API).
+- setup-gemini:       Configure gemini-cli integration.
 `;
 
   program
     .name('eck-snapshot')
     .description('A lightweight, platform-independent CLI for creating project snapshots.')
-    .version('4.0.0')
+    .version('4.1.0')
     .addHelpText('before', helpGuide);
 
   // Main snapshot command
@@ -168,6 +142,7 @@ Useful for a high-level overview.
     .option('--profile <name>', 'Filter files using profiles and/or ad-hoc glob patterns.')
     .option('--agent', 'Generate a snapshot optimized for a command-line agent')
     .option('--with-ja', 'Generate a detailed snapshot for the Junior Architect agent')
+    .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))
     .action(createRepoSnapshot)
     .addHelpText('after', `
@@ -216,6 +191,14 @@ Creating Custom Profiles:
     eck-snapshot profile-detect   (auto-generates profiles using AI)
 `);
 
+  // Update snapshot command
+  program
+    .command('update')
+    .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')
+    .action(updateSnapshot);
+
   // Restore command
   program
     .command('restore')
@@ -423,5 +406,12 @@ Authentication:
     .description('Auto-generate documentation from gemini-extension.json files')
     .action(generateAutoDocs);
 
+  // Show file command (for skeleton mode lazy loading)
+  program
+    .command('show')
+    .description('Output the full content of specific file(s) (for AI lazy loading)')
+    .argument('<filePaths...>', 'Space-separated paths to files')
+    .action(showFile);
+
   program.parse(process.argv);
 }