@xelth/eck-snapshot 5.9.0 → 6.6.0

package/src/cli/cli.js

@@ -2,426 +2,297 @@ import { Command } from 'commander';
 import path from 'path';
 import fs from 'fs/promises';
 import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+import { createRequire } from 'module';
+import os from 'os';
+import crypto from 'crypto';
+import { ensureSnapshotsInGitignore } from '../utils/fileUtils.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-import { createRepoSnapshot } from './commands/createSnapshot.js';
-import { updateSnapshot, updateSnapshotJson } 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 { 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 { pushTelemetry } from '../utils/telemetry.js';
-
-import { showFile } from './commands/showFile.js';
-import { runDoctor } from './commands/doctor.js';
-import { setupMcp } from './commands/setupMcp.js';
-import { envPush, envPull } from './commands/envSync.js';
-import inquirer from 'inquirer';
-import ora from 'ora';
-import { execa } from 'execa';
-import chalk from 'chalk';
-import { createRequire } from 'module';
-
-/**
- * Check code boundaries in a file
- */
-async function checkCodeBoundaries(filePath, agentId) {
+async function getGlobalConfig() {
+  const configPath = path.join(os.homedir(), '.eck', 'cli-config.json');
   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],
-        startIndex: match.index,
-        endIndex: match.index + match[0].length,
-        content: match[2]
-      });
-    }
-
-    return {
-      file: filePath,
-      hasBoundaries: boundaries.length > 0,
-      boundaries: boundaries,
-      canModify: boundaries.every(b => b.owner === agentId || b.owner === 'SHARED')
-    };
-  } catch (error) {
-    return {
-      file: filePath,
-      error: error.message,
-      canModify: true // If can't read, assume can modify (new file)
-    };
+    const data = await fs.readFile(configPath, 'utf-8');
+    return JSON.parse(data);
+  } catch (e) {
+    const newConfig = { instanceId: crypto.randomUUID(), telemetryEnabled: true };
+    await fs.mkdir(path.dirname(configPath), { recursive: true }).catch(() => {});
+    await fs.writeFile(configPath, JSON.stringify(newConfig, null, 2)).catch(() => {});
+    return newConfig;
   }
 }
 
-// Main run function that sets up the CLI
-// Check for newer version on npm (non-blocking)
-function checkForUpdates() {
-  const require = createRequire(import.meta.url);
-  const pkg = require('../../package.json');
-  const currentVersion = pkg.version;
-
-  // Fire and forget — result captured via closure
-  let updateMessage = null;
-
-  const check = execa('npm', ['view', '@xelth/eck-snapshot', 'version'], { timeout: 5000 })
-    .then(({ stdout }) => {
-      const latest = stdout.trim();
-      if (latest && latest !== currentVersion) {
-        const current = currentVersion.split('.').map(Number);
-        const remote = latest.split('.').map(Number);
-        const isNewer = remote[0] > current[0] ||
-          (remote[0] === current[0] && remote[1] > current[1]) ||
-          (remote[0] === current[0] && remote[1] === current[1] && remote[2] > current[2]);
-        if (isNewer) {
-          updateMessage = `\n${chalk.yellow(`⬆ Update available: ${currentVersion} → ${latest}`)}  run: ${chalk.cyan('npm i -g @xelth/eck-snapshot')}`;
-        }
-      }
-    })
-    .catch(() => { /* network error, skip silently */ });
-
-  process.on('exit', () => {
-    if (updateMessage) {
-      console.error(updateMessage);
-    }
-  });
+async function setGlobalConfig(updates) {
+  const configPath = path.join(os.homedir(), '.eck', 'cli-config.json');
+  const current = await getGlobalConfig();
+  const next = { ...current, ...updates };
+  await fs.writeFile(configPath, JSON.stringify(next, null, 2)).catch(() => {});
+  return next;
 }
 
+// Import core logic (we bypass the CLI wrapper entirely)
+import { createRepoSnapshot } from './commands/createSnapshot.js';
+import { updateSnapshot, updateSnapshotJson } from './commands/updateSnapshot.js';
+import { setupMcp } from './commands/setupMcp.js';
+import { detectProject } from './commands/detectProject.js';
+import { runDoctor } from './commands/doctor.js';
+import { runReconTool } from './commands/recon.js';
+import { runTokenTools } from './commands/trainTokens.js';
+
+// Legacy command shims: translate old positional commands to JSON payloads
+// so internal callers (mcp-eck-core.js) keep working after the JSON migration.
+const LEGACY_COMMANDS = {
+  'update-auto': (args) => {
+    const baseIdx = args.indexOf('--base');
+    const base = baseIdx !== -1 && args[baseIdx + 1] ? args[baseIdx + 1] : undefined;
+    return { name: 'eck_update_auto', arguments: { fail: args.includes('--fail') || args.includes('-f'), base } };
+  },
+  'snapshot':    () => ({ name: 'eck_snapshot', arguments: {} }),
+  'update':      (args) => {
+    const baseIdx = args.indexOf('--base');
+    const base = baseIdx !== -1 && args[baseIdx + 1] ? args[baseIdx + 1] : undefined;
+    return { name: 'eck_update', arguments: { fail: args.includes('--fail') || args.includes('-f'), base } };
+  },
+  'setup-mcp':   (args) => ({ name: 'eck_setup_mcp', arguments: { opencode: args.includes('--opencode'), both: args.includes('--both') } }),
+  'detect':      () => ({ name: 'eck_detect', arguments: {} }),
+  'doctor':      () => ({ name: 'eck_doctor', arguments: {} }),
+  'scout':       (args) => ({ name: 'eck_scout', arguments: { depth: args[0] !== undefined ? parseInt(args[0], 10) : 0 } }),
+  'fetch':       (args) => ({ name: 'eck_fetch', arguments: { patterns: args } }),
+  'link':        (args) => ({ name: 'eck_snapshot', arguments: { isLinkedProject: true, linkDepth: args[0] !== undefined ? parseInt(args[0], 10) : 0 } }),
+  'profile':     (args) => args[0] ? ({ name: 'eck_snapshot', arguments: { profile: args.join(',') } }) : ({ name: 'eck_snapshot', arguments: { profile: true } }),
+  'booklm':      () => ({ name: 'eck_snapshot', arguments: { notebooklm: 'scout' } }),
+  'notelm':      () => ({ name: 'eck_snapshot', arguments: { notebooklm: 'architect' } }),
+  'notebook':    (args) => {
+    if (args[0] === 'link') return { name: 'eck_snapshot', arguments: { notebooklm: 'link', linkDepth: args[1] !== undefined ? parseInt(args[1], 10) : 0 } };
+    if (args[0] === 'scout') return { name: 'eck_snapshot', arguments: { notebooklm: 'scout', linkDepth: args[1] !== undefined ? parseInt(args[1], 10) : 0 } };
+    return { name: 'eck_snapshot', arguments: { notebooklm: 'hybrid' } };
+  },
+  'telemetry':   (args) => ({ name: 'eck_telemetry', arguments: { action: args[0] } }),
+};
+
 export function run() {
-  // Start version check in background (non-blocking)
-  checkForUpdates();
+  // Intercept legacy positional commands before commander parses them
+  const rawArgs = process.argv.slice(2);
+  const firstArg = rawArgs[0];
+  if (firstArg && LEGACY_COMMANDS[firstArg]) {
+    const payload = LEGACY_COMMANDS[firstArg](rawArgs.slice(1));
+    // Replace argv so commander sees the JSON payload
+    process.argv = [process.argv[0], process.argv[1], JSON.stringify(payload)];
+  }
 
   const program = new Command();
-
   const pkg = createRequire(import.meta.url)('../../package.json');
-  const helpGuide = `eck-snapshot (v${pkg.version}) - 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                         (List all profiles)
-   $ eck-snapshot --profile backend                 (Use profile)
-   $ 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.
-- setup-mcp:          Setup/restore MCP servers (eck-core + glm-zai).
+  const helpGuide = `
+eck-snapshot (v${pkg.version}) - AI-Native Repository Context Tool.
+===================================================================
+
+[AI AGENTS: PURE JSON/MCP INTERFACE ACTIVE]
+This CLI is designed to be operated by AI agents using JSON payloads.
+  - eck_snapshot    : { profile, skeleton, jas, link, linkDepth }
+  - eck_update      : Delta snapshot
+  - eck_scout       : { depth: 0-9 }
+  - eck_fetch       : { patterns: [] }
+  - eck_setup_mcp   : Configure MCP servers
+  - eck_detect      : Detect project type
+  - eck_doctor      : Health check
+
+[HUMAN COMMANDS: SHORTHANDS]
+Ranked by frequency of use:
+
+  1. eck-snapshot snapshot          Full project snapshot
+  2. eck-snapshot update            Delta update (changed files only)
+                                     --base <snapshot.md> : Compare against an old snapshot file
+  3. eck-snapshot profile [name]    Snapshot filtered by profile (from .eck/profiles.json)
+                                     No arg = list available profiles
+                                     Example: eck-snapshot profile backend
+                                     Multiple: eck-snapshot profile backend,api
+  4. eck-snapshot scout [0-9]       Scout external repo. Depths:
+                                      0: Tree only (default)
+                                      1-4: Truncated (10, 30, 60, 100 lines)
+                                      5: Skeleton (Signatures only)
+                                      6: Skeleton + docs
+                                      7-9: Full content (500, 1000, unlimited)
+  5. eck-snapshot fetch <glob>      Fetch specific files (e.g., "src/**/*.js")
+  6. eck-snapshot link [0-9]        Linked companion snapshot (same depths)
+  7. eck-snapshot booklm            Export for NotebookLM (Scout - fetch generator)
+  8. eck-snapshot notelm            Export for NotebookLM (Architect - experimental)
+  9. eck-snapshot notebook          Export for NotebookLM (Primary Project)
+       eck-snapshot notebook link 5   Export Linked Project for NotebookLM (chunked)
+       eck-snapshot notebook scout 5  Export Scouted Project for NotebookLM (chunked)
+ 10. eck-snapshot setup-mcp         Configure AI agents (Claude Code, OpenCode)
+ 10. eck-snapshot detect            Detect project type and active filters
+ 11. eck-snapshot doctor            Check project health and stubs
+
+[FEEDBACK]
+  eck-snapshot -e "message"     Send feedback/ideas to developers (read by AI)
+  eck-snapshot -E "message"     Send urgent bug report
+
+[DATENSCHUTZ / PRIVACY]
+  We respect your privacy. By default, eck-snapshot collects anonymous usage counts
+  and crash logs to improve the tool. NO source code or sensitive data is ever sent.
+  To completely disable background telemetry:
+    eck-snapshot telemetry disable
+  To re-enable it:
+    eck-snapshot telemetry enable
 `;
 
   program
     .name('eck-snapshot')
-    .description('A lightweight, platform-independent CLI for creating project snapshots.')
     .version(pkg.version)
-    .addHelpText('before', helpGuide);
-
-  // Main snapshot command
-  program
-    .command('snapshot', { isDefault: true })
-    .description('Create a multi-agent aware snapshot of a repository')
-    .argument('[repoPath]', 'Path to the repository', process.cwd())
-    .option('-o, --output <dir>', 'Output directory')
-    .option('--no-tree', 'Exclude directory tree')
-    .option('-v, --verbose', 'Show detailed processing')
-    .option('--max-file-size <size>', 'Maximum file size', '10MB')
-    .option('--max-total-size <size>', 'Maximum total size', '100MB')
-    .option('--max-depth <number>', 'Maximum tree depth', (val) => parseInt(val), 10)
-    .option('--config <path>', 'Configuration file path')
-    .option('--include-hidden', 'Include hidden files')
-    .option('--format <type>', 'Output format: md, json', 'md')
-    .option('--no-ai-header', 'Skip AI instructions')
-    .option('-d, --dir', 'Directory mode')
-    .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('--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))
-    .action(createRepoSnapshot)
-    .addHelpText('after', `
-Quick --profile Examples:
-  --profile                              List all available profiles
-  --profile backend                      Use the 'backend' profile
-  --profile "backend,-**/tests/**"       Use backend, exclude tests
-  --profile "src/**/*.js,-**/*.test.js"  Ad-hoc: all JS, exclude tests
-
-  See "Managing Context Profiles" section above for profile setup.
-`);
-
-  // 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);
-
-  // Auto/Silent Update command for Agents
-  program
-    .command('update-auto')
-    .description('Silent update for AI agents (JSON output)')
-    .argument('[repoPath]', 'Path to the repository', process.cwd())
-    .action(updateSnapshotJson);
-
-  // Restore command
-  program
-    .command('restore')
-    .description('Restore files from a snapshot')
-    .argument('<snapshot_file>', 'Snapshot file path')
-    .argument('[target_directory]', 'Target directory', process.cwd())
-    .option('-f, --force', 'Skip confirmation')
-    .option('-v, --verbose', 'Show detailed progress')
-    .option('--dry-run', 'Preview without writing')
-    .option('--include <patterns...>', 'Include patterns')
-    .option('--exclude <patterns...>', 'Exclude patterns')
-    .option('--concurrency <number>', 'Concurrent operations', (val) => parseInt(val), 10)
-    .action(restoreSnapshot);
-
-  // Prune command
-  program
-    .command('prune')
-    .description('Intelligently reduce snapshot size using AI file ranking')
-    .argument('<snapshot_file>', 'Path to the snapshot file to prune')
-    .option('--target-size <size>', 'Target size (e.g., 500KB, 1MB)', '500KB')
-    .action(pruneSnapshot);
-
-  // Consilium command
-  program
-    .command('consilium')
-    .description('Generate a consilium request for complex decisions')
-    .option('--type <type>', 'Decision type', 'technical_decision')
-    .option('--title <title>', 'Decision title')
-    .option('--description <desc>', 'Detailed description')
-    .option('--complexity <num>', 'Complexity score (1-10)', (val) => parseInt(val), 7)
-    .option('--constraints <list>', 'Comma-separated constraints')
-    .option('--snapshot <file>', 'Include snapshot file')
-    .option('--agent <id>', 'Requesting agent ID')
-    .option('-o, --output <file>', 'Output file', 'consilium_request.json')
-    .action(generateConsilium);
-
-  // Check boundaries command
-  program
-    .command('check-boundaries')
-    .description('Check agent boundaries in a file')
-    .argument('<file>', 'File to check')
-    .option('--agent <id>', 'Your agent ID')
-    .action(async (file, options) => {
-      const result = await checkCodeBoundaries(file, options.agent || 'UNKNOWN');
-      console.log(JSON.stringify(result, null, 2));
-    });
-
-  // Project detection command
-  program
-    .command('detect')
-    .description('Detect and display project type and configuration')
-    .argument('[projectPath]', 'Path to the project', process.cwd())
-    .option('-v, --verbose', 'Show detailed detection results')
-    .action(detectProject);
-
-  // Android parsing test command
-  program
-    .command('test-android')
-    .description('Test Android file parsing capabilities')
-    .argument('<filePath>', 'Path to Android source file (.kt or .java)')
-    .option('--show-content', 'Show content preview of parsed segments')
-    .action(testFileParsing);
-
-  // Token training command
-  program
-    .command('train-tokens')
-    .description('Train token estimation with actual results')
-    .argument('<projectType>', 'Project type (android, nodejs, python, etc.)')
-    .argument('<fileSizeBytes>', 'File size in bytes')
-    .argument('<estimatedTokens>', 'Estimated token count')
-    .argument('<actualTokens>', 'Actual token count from LLM')
-    .action(trainTokens);
-
-  // Token statistics command
-  program
-    .command('token-stats')
-    .description('Show token estimation statistics and accuracy')
-    .action(showTokenStats);
-
-  // Profile detection command
-  program
-    .command('profile-detect')
-    .description('Use AI to scan the directory tree and auto-generate local context profiles (saves to .eck/profiles.json)')
-    .argument('[repoPath]', 'Path to the repository', process.cwd())
-    .action(detectProfiles);
+    .addHelpText('before', helpGuide)
+    .argument('[payload]', 'JSON string representing the MCP tool call')
+    .option('-e, --feedback <message>', 'Send feedback or report an issue to developers')
+    .option('-E, --urgent-feedback <message>', 'Send urgent feedback to developers')
+    .action(async (payloadStr, options) => {
+      const globalConfig = await getGlobalConfig();
+
+      // --- Handle Feedback Flags ---
+      if (options.feedback || options.urgentFeedback) {
+        const msg = options.feedback || options.urgentFeedback;
+        const type = options.urgentFeedback ? 'URGENT' : 'NORMAL';
+        const queuePath = path.join(process.cwd(), '.eck', 'telemetry_queue.json');
+
+        let queue = { instanceId: globalConfig.instanceId, feedback: [], usage: {}, errors: [] };
+        try {
+          const existing = JSON.parse(await fs.readFile(queuePath, 'utf-8'));
+          queue = { ...queue, ...existing };
+        } catch(e) { /* no existing queue */ }
+
+        queue.feedback.push({ type, message: msg, date: new Date().toISOString() });
+
+        await fs.mkdir(path.dirname(queuePath), { recursive: true }).catch(() => {});
+        await ensureSnapshotsInGitignore(process.cwd()).catch(() => {});
+        await fs.writeFile(queuePath, JSON.stringify(queue, null, 2));
+
+        console.log(chalk.green('Feedback saved locally. It will be sent to developers during the next telemetry sync.'));
+        console.log(chalk.gray('(Note: Messages are processed by AI for developers)'));
+        return;
+      }
 
-  program
-    .command('generate-profile-guide')
-    .description('Generate a markdown guide with a prompt and directory tree for manual profile creation')
-    .argument('[repoPath]', 'Path to the repository', process.cwd())
-    .option('--config <path>', 'Configuration file path')
-    .action((repoPath, options) => generateProfileGuide(repoPath, options));
+      // Default behavior for human users: empty call = full snapshot
+      if (!payloadStr) {
+        console.log(chalk.cyan('🚀 No arguments provided. Defaulting to full repository snapshot...'));
+        console.log(chalk.gray('💡 Run `eck-snapshot -h` to see all available JSON tools.\n'));
+        payloadStr = '{"name": "eck_snapshot", "arguments": {}}';
+      }
 
-  // Ask Claude command
-  program
-    .command('ask-claude')
-    .description('Execute a prompt using claude-code CLI and return JSON response')
-    .argument('<prompt>', 'Prompt to send to Claude')
-    .option('-c, --continue', 'Continue the most recent conversation')
-    .action(async (prompt, options) => {
+      let payload;
       try {
-        const result = await executePrompt(prompt, options.continue);
-        console.log(JSON.stringify(result, null, 2));
-      } catch (error) {
-        console.error(`Failed to execute prompt: ${error.message}`);
+        payload = JSON.parse(payloadStr.trim());
+      } catch (e) {
+        console.error(chalk.red('❌ Error: Input must be a valid JSON string.'));
+        console.log(chalk.yellow(`Example: eck-snapshot '{"name": "eck_snapshot"}'`));
         process.exit(1);
       }
-    });
 
-  // Ask Claude with specific session
-  program
-    .command('ask-claude-session')
-    .description('Execute a prompt using specific session ID')
-    .argument('<sessionId>', 'Session ID to resume')
-    .argument('<prompt>', 'Prompt to send to Claude')
-    .action(async (sessionId, prompt) => {
-      try {
-        // Directly use the provided session ID
-        const result = await executePromptWithSession(prompt, sessionId);
-        console.log(JSON.stringify(result, null, 2));
-      } catch (error) {
-        console.error('Failed to execute prompt:', error.message);
-        process.exit(1);
+      const toolName = payload.name;
+      const args = payload.arguments || {};
+
+      // --- Handle Telemetry Config Command ---
+      if (toolName === 'eck_telemetry') {
+        if (args.action === 'disable') {
+          await setGlobalConfig({ telemetryEnabled: false });
+          console.log(chalk.yellow('Background telemetry has been disabled.'));
+        } else if (args.action === 'enable') {
+          await setGlobalConfig({ telemetryEnabled: true });
+          console.log(chalk.green('Background telemetry has been enabled. Thank you for supporting the project!'));
+        } else {
+          console.log(chalk.blue(`Telemetry is currently: ${globalConfig.telemetryEnabled ? 'ENABLED' : 'DISABLED'}`));
+          console.log(chalk.gray(`Instance ID: ${globalConfig.instanceId}`));
+        }
+        return;
       }
-    });
 
+      const cwd = process.cwd();
+      const queuePath = path.join(cwd, '.eck', 'telemetry_queue.json');
 
+      try {
+        // --- Track Usage Locally (Guarded by Privacy Opt-in) ---
+        if (globalConfig.telemetryEnabled) {
+          try {
+            let queue = { instanceId: globalConfig.instanceId, feedback: [], usage: {}, errors: [] };
+            try {
+              const existing = JSON.parse(await fs.readFile(queuePath, 'utf-8'));
+              queue = { ...queue, ...existing };
+            } catch(e) { /* no existing queue */ }
+            queue.usage[toolName] = (queue.usage[toolName] || 0) + 1;
+            await fs.mkdir(path.dirname(queuePath), { recursive: true }).catch(() => {});
+            await ensureSnapshotsInGitignore(cwd).catch(() => {});
+            await fs.writeFile(queuePath, JSON.stringify(queue, null, 2));
+          } catch(e) { /* ignore tracking errors */ }
+        }
 
+        switch (toolName) {
+          case 'eck_snapshot':
+            await createRepoSnapshot(cwd, args);
+            break;
+          case 'eck_update':
+            await updateSnapshot(cwd, args);
+            break;
+          case 'eck_update_auto':
+            await updateSnapshotJson(cwd, args);
+            break;
+          case 'eck_setup_mcp':
+            await setupMcp(args);
+            break;
+          case 'eck_detect':
+            await detectProject(cwd, args);
+            break;
+          case 'eck_doctor':
+            await runDoctor(cwd);
+            break;
+          case 'eck_scout':
+          case 'eck_fetch':
+            await runReconTool(payload);
+            break;
+          case 'eck_train_tokens':
+          case 'eck_token_stats':
+            await runTokenTools(payload);
+            break;
+          default:
+            console.log(chalk.red(`❌ Unknown tool: "${toolName}"`));
+            console.log(chalk.yellow('Run `eck-snapshot -h` to see available JSON tools.'));
+            process.exit(1);
+        }
+      } catch (err) {
+        // --- Track Errors Locally (Guarded by Privacy Opt-in) ---
+        if (globalConfig.telemetryEnabled) {
+          try {
+            let queue = { instanceId: globalConfig.instanceId, feedback: [], usage: {}, errors: [] };
+            try {
+              const existing = JSON.parse(await fs.readFile(queuePath, 'utf-8'));
+              queue = { ...queue, ...existing };
+            } catch(e) { /* no existing queue */ }
+            queue.errors.push({ tool: toolName, error: err.message, date: new Date().toISOString() });
+            await fs.mkdir(path.dirname(queuePath), { recursive: true }).catch(() => {});
+            await ensureSnapshotsInGitignore(cwd).catch(() => {});
+            await fs.writeFile(queuePath, JSON.stringify(queue, null, 2));
+          } catch(e) { /* ignore tracking errors */ }
+        }
 
-  program
-    .command('generate-ai-prompt')
-    .description('Generate a specific AI prompt from a template.')
-    .option('--role <role>', 'The role for which to generate a prompt', 'architect')
-    .action(async (options) => {
-      try {
-        const templatePath = path.join(__dirname, '..', 'templates', `${options.role}-prompt.template.md`);
-        const template = await fs.readFile(templatePath, 'utf-8');
-        // In the future, we can inject dynamic data here from setup.json
-        console.log(template);
-      } catch (error) {
-        console.error(`Failed to generate prompt for role '${options.role}':`, error.message);
+        console.error(chalk.red(`❌ Execution failed for ${toolName}:`), err.message);
         process.exit(1);
       }
     });
 
-  // Setup Gemini command
-  program
-    .command('setup-gemini')
-    .description('Generate claude.toml configuration for gemini-cli integration with dynamic paths')
-    .option('-v, --verbose', 'Show detailed output and error information')
-    .action(setupGemini);
-
-
-  // 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);
-
-  // Setup MCP servers command (replaces setup-claude-mcp with unified approach)
-  program
-    .command('setup-mcp')
-    .description('Setup/restore MCP servers (eck-core + glm-zai) for Claude Code and/or OpenCode')
-    .option('--opencode', 'Setup for OpenCode only')
-    .option('--both', 'Setup for both Claude Code and OpenCode')
-    .option('-v, --verbose', 'Show detailed output')
-    .action(setupMcp);
-
-  // Environment sync commands (encrypted .eck/ transfer between machines)
-  const envCmd = program.command('env').description('Encrypted environment sync');
-  envCmd
-    .command('push')
-    .description('Pack and encrypt .eck/ config files into .eck-sync.enc')
-    .option('-v, --verbose', 'Show detailed output')
-    .action(envPush);
-  envCmd
-    .command('pull')
-    .description('Decrypt and restore .eck/ config files from .eck-sync.enc')
-    .option('-f, --force', 'Overwrite existing .eck/ files without prompting')
-    .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();
-    });
+  // Start version check in background (non-blocking)
+  checkForUpdates(pkg.version);
 
   program.parse(process.argv);
 }
+
+function checkForUpdates(currentVersion) {
+  import('execa').then(({ execa }) => {
+    execa('npm', ['view', '@xelth/eck-snapshot', 'version'], { timeout: 5000 })
+      .then(({ stdout }) => {
+        const latest = stdout.trim();
+        if (latest && latest !== currentVersion) {
+          console.error(`\n${chalk.yellow(`⬆ Update available: ${currentVersion} → ${latest}`)}`);
+        }
+      })
+      .catch(() => {});
+  });
+}