@xelth/eck-snapshot 6.4.2 → 6.4.3

package/README.md

@@ -36,6 +36,8 @@ Pass the Architect's technical plan to your local **Coder agent** (Claude Code /
 ### 3. Auto-Updates
 When the Coder agent finishes a task, it automatically calls the built-in MCP tool (`eck_finish_task`), which commits the code and generates an incremental delta update snapshot. Feed that update back to the Architect to keep it in sync.
 
+> **Custom base:** Use `eck-snapshot update --base <snapshot.md>` to generate a delta relative to any past snapshot file. Pass the filename (e.g. `eckRepo26-04-01_f2e1bd4_up1_29kb.md`) — the anchor hash is extracted automatically. This doesn't disturb the automatic sequence counter — custom-base snapshots get a `_upcustom` suffix. A raw git hash (7+ hex chars) also works.
+
 ---
 
 ## 🧠 Which Models to Use
@@ -83,7 +85,7 @@ For humans typing in the terminal, short commands work too:
 | # | Command | Description |
 |---|---------|-------------|
 | 1 | `eck-snapshot snapshot` | Full project snapshot |
-| 2 | `eck-snapshot update` | Delta update (changed files only) |
+| 2 | `eck-snapshot update` | Delta update (changed files only). Supports `--base <snapshot.md>` to compare against an old snapshot file. |
 | 3 | `eck-snapshot profile [name]` | Snapshot filtered by profile (no arg = list profiles) |
 | 4 | `eck-snapshot scout [0-9]` | Scout external repo (see depth scale below) |
 | 5 | `eck-snapshot fetch "src/**/*.rs"` | Fetch specific files by glob |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xelth/eck-snapshot",
-  "version": "6.4.2",
+  "version": "6.4.3",
   "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.",
   "keywords": [
     "ai",

package/src/cli/cli.js

@@ -43,9 +43,17 @@ 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) => ({ name: 'eck_update_auto', arguments: { fail: args.includes('--fail') || args.includes('-f') } }),
+  '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) => ({ name: 'eck_update', arguments: { fail: args.includes('--fail') || args.includes('-f') } }),
+  '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: {} }),
@@ -90,6 +98,7 @@ 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

package/src/cli/commands/updateSnapshot.js

@@ -37,6 +37,15 @@ async function autoCommit(repoPath) {
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
+function resolveBaseHash(base) {
+  if (!base) return null;
+  const basename = path.basename(base, '.md');
+  const match = basename.match(/_([0-9a-f]{7,40})_/);
+  if (match) return match[1];
+  if (/^[0-9a-f]{7,40}$/i.test(base)) return base;
+  throw new Error(`Invalid --base value: "${base}". Expected a snapshot filename or a git commit hash.`);
+}
+
 // Shared logic to generate the snapshot content string
 async function generateSnapshotContent(repoPath, changedFiles, anchor, config, gitignore) {
   let contentOutput = '';
@@ -160,7 +169,9 @@ async function generateSnapshotContent(repoPath, changedFiles, anchor, config, g
 export async function updateSnapshot(repoPath, options) {
   const spinner = ora('Generating update snapshot...').start();
   try {
-    const anchor = await getGitAnchor(repoPath);
+    const isCustomBase = !!options.base;
+    const anchor = resolveBaseHash(options.base) || await getGitAnchor(repoPath);
+
     if (!anchor) {
       throw new Error('No snapshot anchor found. Run a full snapshot first: eck-snapshot snapshot');
     }
@@ -175,6 +186,11 @@ export async function updateSnapshot(repoPath, options) {
     } else {
       spinner.info('Fail flag passed: skipping auto-commit.');
     }
+
+    if (isCustomBase) {
+      spinner.info(`Using custom base: ${anchor.substring(0, 7)} (from ${path.basename(options.base)})`);
+    }
+
     spinner.start('Generating update snapshot...');
 
     const changedFiles = await getChangedFiles(repoPath, anchor, options.fail);
@@ -203,24 +219,28 @@ export async function updateSnapshot(repoPath, options) {
     const { fullContent, includedCount, agentReport } = await generateSnapshotContent(repoPath, changedFiles, anchor, config, gitignore);
 
     // Determine sequence number
-    let seqNum = 1;
-    const counterPath = path.join(repoPath, '.eck', 'update_seq');
-    try {
-      const seqData = await fs.readFile(counterPath, 'utf-8');
-      const [savedHash, savedCount] = seqData.split(':');
-      if (savedHash && savedHash.trim() === anchor.substring(0, 7).trim()) {
-        seqNum = parseInt(savedCount || '0') + 1;
-      }
-    } catch (e) {}
+    let seqStr = 'custom';
+    if (!isCustomBase) {
+      let seqNum = 1;
+      const counterPath = path.join(repoPath, '.eck', 'update_seq');
+      try {
+        const seqData = await fs.readFile(counterPath, 'utf-8');
+        const [savedHash, savedCount] = seqData.split(':');
+        if (savedHash && savedHash.trim() === anchor.substring(0, 7).trim()) {
+          seqNum = parseInt(savedCount || '0') + 1;
+        }
+      } catch (e) {}
 
-    try {
-      await fs.writeFile(counterPath, `${anchor.substring(0, 7)}:${seqNum}`);
-    } catch (e) {}
+      try {
+        await fs.writeFile(counterPath, `${anchor.substring(0, 7)}:${seqNum}`);
+      } catch (e) {}
+      seqStr = seqNum.toString();
+    }
 
     const timestamp = generateTimestamp();
     const shortRepoName = getShortRepoName(path.basename(repoPath));
     const sizeKB = Math.max(1, Math.round(Buffer.byteLength(fullContent, 'utf-8') / 1024));
-    const outputFilename = `eck${shortRepoName}${timestamp}_${anchor.substring(0, 7)}_up${seqNum}_${sizeKB}kb.md`;
+    const outputFilename = `eck${shortRepoName}${timestamp}_${anchor.substring(0, 7)}_up${seqStr}_${sizeKB}kb.md`;
     const outputPath = path.join(repoPath, '.eck', 'snapshots', outputFilename);
 
     await fs.mkdir(path.dirname(outputPath), { recursive: true });
@@ -267,7 +287,9 @@ export async function updateSnapshot(repoPath, options) {
 // New Silent/JSON command for Agents
 export async function updateSnapshotJson(repoPath, options = {}) {
   try {
-    const anchor = await getGitAnchor(repoPath);
+    const isCustomBase = !!options.base;
+    const anchor = resolveBaseHash(options.base) || await getGitAnchor(repoPath);
+    
     if (!anchor) {
       console.log(JSON.stringify({ status: "error", message: "No snapshot anchor found" }));
       return;
@@ -303,24 +325,28 @@ export async function updateSnapshotJson(repoPath, options = {}) {
 
     const { fullContent, includedCount, agentReport } = await generateSnapshotContent(repoPath, changedFiles, anchor, config, gitignore);
 
-    let seqNum = 1;
-    const counterPath = path.join(repoPath, '.eck', 'update_seq');
-    try {
-      const seqData = await fs.readFile(counterPath, 'utf-8');
-      const [savedHash, savedCount] = seqData.split(':');
-      if (savedHash && savedHash.trim() === anchor.substring(0, 7).trim()) {
-        seqNum = parseInt(savedCount || '0') + 1;
-      }
-    } catch (e) {}
+    let seqStr = 'custom';
+    if (!isCustomBase) {
+      let seqNum = 1;
+      const counterPath = path.join(repoPath, '.eck', 'update_seq');
+      try {
+        const seqData = await fs.readFile(counterPath, 'utf-8');
+        const [savedHash, savedCount] = seqData.split(':');
+        if (savedHash && savedHash.trim() === anchor.substring(0, 7).trim()) {
+          seqNum = parseInt(savedCount || '0') + 1;
+        }
+      } catch (e) {}
 
-    try {
-      await fs.writeFile(counterPath, `${anchor.substring(0, 7)}:${seqNum}`);
-    } catch (e) {}
+      try {
+        await fs.writeFile(counterPath, `${anchor.substring(0, 7)}:${seqNum}`);
+      } catch (e) {}
+      seqStr = seqNum.toString();
+    }
 
     const timestamp = generateTimestamp();
     const shortRepoName = getShortRepoName(path.basename(repoPath));
     const sizeKB = Math.max(1, Math.round(Buffer.byteLength(fullContent, 'utf-8') / 1024));
-    const outputFilename = `eck${shortRepoName}${timestamp}_${anchor.substring(0, 7)}_up${seqNum}_${sizeKB}kb.md`;
+    const outputFilename = `eck${shortRepoName}${timestamp}_${anchor.substring(0, 7)}_up${seqStr}_${sizeKB}kb.md`;
     const outputPath = path.join(repoPath, '.eck', 'snapshots', outputFilename);
     await fs.mkdir(path.dirname(outputPath), { recursive: true });
     await fs.writeFile(outputPath, fullContent);