@xelth/eck-snapshot 4.0.0 → 4.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xelth/eck-snapshot",
-  "version": "4.0.0",
+  "version": "4.2.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",
@@ -19,8 +19,7 @@
     "test": "vitest",
     "test:ui": "vitest --ui",
     "test:run": "vitest run",
-    "docs:auto": "node index.js docs-auto",
-    "test:gpt": "vitest src/services/gptService.test.js"
+    "docs:auto": "node index.js docs-auto"
   },
   "author": "xelth-com",
   "license": "MIT",
@@ -29,6 +28,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",
@@ -40,11 +40,21 @@
     "inquirer": "^9.2.20",
     "is-binary-path": "^2.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/setup.json

@@ -231,16 +231,13 @@
   },
   "contextProfiles": {
     "backend": {
-      "description": "Backend API, database, business logic",
+      "description": "Backend API, services, business logic",
       "include": [
         "packages/backend/**",
-        "packages/core/**",
-        "knexfile.js",
-        "migrations/**"
+        "packages/core/**"
       ],
       "exclude": [
         "**/*.test.*",
-        "**/*.sqlite*",
         "node_modules/**"
       ]
     },
@@ -301,8 +298,7 @@
       "description": "Database schema and migrations only",
       "include": [
         "**/migrations/**",
-        "**/knexfile.js",
-        "**/schema.sql"
+        "**/schema/**"
       ]
     },
     "deployment": {
@@ -374,7 +370,6 @@
     "dirsToIgnore": [
       "node_modules/",
       ".git/",
-      ".eck/",
       "dist/",
       "build/",
       ".next/",
@@ -387,6 +382,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": [
@@ -524,6 +540,10 @@
     "maxDepth": 10,
     "concurrency": 10
   },
+  "security": {
+    "scanForSecrets": true,
+    "_comment": "Automatically detects and redacts API keys, tokens, and credentials in snapshots to prevent accidental exposure"
+  },
   "output": {
     "defaultFormat": "md",
     "defaultPath": "./.eck/snapshots",
@@ -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",
@@ -647,25 +671,6 @@
           "no hardware debugging interfaces"
         ]
       },
-      "ci_cd": {
-        "active": false,
-        "name": "CI/CD Pipeline Agent (AGENT_CI_CD)",
-        "description": "Automated testing and deployment pipeline",
-        "guiSupport": false,
-        "capabilities": [
-          "npm ci",
-          "npm test",
-          "npm run build",
-          "docker build",
-          "artifact generation"
-        ],
-        "restrictions": [
-          "no interactive commands",
-          "no GUI applications",
-          "no watch modes",
-          "no development servers"
-        ]
-      },
       "gemini_wsl": {
         "active": true,
         "name": "Gemini WSL Agent (Junior Architect)",
@@ -713,6 +718,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"
@@ -721,7 +744,6 @@
       "envScanRequest": "src/templates/envScanRequest.md",
       "gitWorkflow": "src/templates/gitWorkflow.md",
       "multiAgent": "src/templates/multiAgent.md",
-      "vectorMode": "src/templates/vectorMode.md",
       "agent": "src/templates/agent-prompt.template.md"
     }
   },
@@ -760,11 +782,11 @@
       },
       "database_expert": {
         "active": true,
-        "modelName": "GPT-4/Claude",
+        "modelName": "Claude",
         "role": "Database Specialist",
         "strengths": [
-          "PostgreSQL optimization",
-          "Knex migrations",
+          "Schema design",
+          "Query optimization",
           "data integrity"
         ]
       },

package/src/cli/cli.js

@@ -7,18 +7,19 @@ 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';
 import { detectProject, testFileParsing } from './commands/detectProject.js';
 import { trainTokens, showTokenStats } from './commands/trainTokens.js';
-import { askGpt } from './commands/askGpt.js';
-import { ask as askGptService } from '../services/gptService.js';
 import { executePrompt, executePromptWithSession } from '../services/claudeCliService.js';
 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 { runDoctor } from './commands/doctor.js';
 import inquirer from 'inquirer';
 import ora from 'ora';
 import { execa } from 'execa';
@@ -31,10 +32,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 +44,7 @@ async function checkCodeBoundaries(filePath, agentId) {
         content: match[2]
       });
     }
-    
+
     return {
       file: filePath,
       hasBoundaries: boundaries.length > 0,
@@ -63,89 +64,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-claude:        Delegate tasks to Claude CLI agent.
+- 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 +141,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 +190,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')
@@ -263,47 +245,6 @@ Creating Custom Profiles:
       console.log(JSON.stringify(result, null, 2));
     });
 
-  program
-    .command('ask-gpt')
-    .description('Delegate tasks to OpenAI Codex agent with automatic authentication')
-    .argument('<payload>', 'JSON payload string (e.g. \'{"objective": "Calculate 5+2"}\')')
-    .option('-v, --verbose', 'Enable verbose logging and detailed execution output')
-    .option('--model <name>', 'Model to use (default: gpt-5-codex)', 'gpt-5-codex')
-    .option('--reasoning <level>', 'Reasoning level: low, medium, high (default: high)', 'high')
-    .action((payloadArg, cmd) => askGpt(payloadArg, cmd))
-    .addHelpText('after', `
-Examples:
-  Ask a simple question:
-    eck-snapshot ask-gpt '{"objective": "What is 5+2?"}'
-
-  Request code changes with context:
-    eck-snapshot ask-gpt '{
-      "target_agent": "local_dev",
-      "task_id": "feature-123",
-      "payload": {
-        "objective": "Add error handling to login function",
-        "files_to_modify": [{"path": "src/auth.js", "action": "modify"}]
-      },
-      "post_execution_steps": {
-        "journal_entry": {
-          "type": "feat",
-          "scope": "auth",
-          "summary": "Add error handling"
-        }
-      }
-    }' --verbose
-
-Prerequisites:
-  1. Install Codex CLI: npm install -g @openai/codex
-  2. Login: codex login (requires ChatGPT Plus/Pro subscription)
-  3. The command automatically loads .eck project context
-
-Authentication:
-  - Uses your existing 'codex login' credentials
-  - Auto-retries on authentication errors
-  - Supports ChatGPT Plus/Pro subscriptions
-`);
-
   // Project detection command
   program
     .command('detect')
@@ -361,16 +302,8 @@ Authentication:
         const result = await executePrompt(prompt, options.continue);
         console.log(JSON.stringify(result, null, 2));
       } catch (error) {
-        console.warn(`⚠️ Claude failed: ${error.message}`);
-        console.log('🔄 Failing over to GPT for task...');
-        try {
-          const payload = (typeof prompt === 'string' && prompt.startsWith('{')) ? prompt : JSON.stringify({ objective: prompt });
-          const gptResult = await askGptService(payload, { verbose: false });
-          console.log(JSON.stringify(gptResult, null, 2));
-        } catch (gptError) {
-          console.error('Failed to execute prompt with both Claude and GPT:', gptError.message);
-          process.exit(1);
-        }
+        console.error(`Failed to execute prompt: ${error.message}`);
+        process.exit(1);
       }
     });
 
@@ -423,5 +356,19 @@ 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);
+
+  // Doctor command (health check for manifests)
+  program
+    .command('doctor')
+    .description('Check project health and detect unfinished manifest stubs')
+    .argument('[repoPath]', 'Path to the repository', process.cwd())
+    .action(runDoctor);
+
   program.parse(process.argv);
 }

package/src/cli/commands/autoDocs.js

@@ -19,38 +19,7 @@ export async function generateAutoDocs() {
       await fs.access(extensionsDir);
     } catch (error) {
       console.log(`Extensions directory not found at: ${extensionsDir}`);
-      console.log('Creating example structure...');
-
-      // Create the directory structure
-      await fs.mkdir(extensionsDir, { recursive: true });
-
-      // Create a sample gemini-extension.json file for demonstration
-      const sampleExtension = {
-        name: "sample-extension",
-        description: "Sample Gemini extension for demonstration",
-        commands: [
-          {
-            name: "sample-command",
-            description: "A sample command for testing auto-docs",
-            usage: "sample-command [options]",
-            examples: ["sample-command --help"]
-          }
-        ],
-        tools: [
-          {
-            name: "sample-tool",
-            description: "A sample tool for testing auto-docs",
-            usage: "Use this tool for sample operations"
-          }
-        ]
-      };
-
-      await fs.writeFile(
-        path.join(extensionsDir, 'sample-extension.json'),
-        JSON.stringify(sampleExtension, null, 2)
-      );
-
-      console.log('Created sample extension at:', path.join(extensionsDir, 'sample-extension.json'));
+      return;
     }
 
     // Read all JSON files in the extensions directory