@fizzyflow/wdoublesync_cli 1.0.7 → 1.0.8

package/README.md

@@ -24,6 +24,7 @@ pnpm link --global
 wdoublesync push [vector-id] [path] [options]   Sync folder to a vector (creates one if no id given)
 wdoublesync pull <vector-id> [path] [options]   Restore vector contents to a folder
 wdoublesync info [vector-id] [path] [options]   Show chain/wallet info, or full vector metadata
+wdoublesync diff <vector-id> [path] [options]   List files added/modified/deleted locally vs the on-chain version
 wdoublesync watch <vector-id> [path] [options]  Watch folder: auto-push on changes, auto-pull on remote updates
 wdoublesync rebate <vector-id> [path] [options] Burn archive patches and push folder as a fresh snapshot
 ```
@@ -37,7 +38,7 @@ The `[path]` argument is optional — if omitted, the current working directory
 | `--chain <name>` | Chain: `mainnet`, `testnet`, `devnet`, `localnet` (default: `testnet`) |
 | `--key <suiprivkey>` | Sui private key (or set `WDOUBLESYNC_KEY` env var) |
 | `--phrase <mnemonic>` | Mnemonic phrase instead of a raw key |
-| `--version <n>` | Version to restore (`pull` only, default: latest) |
+| `--version <n>` | Version to restore or compare against (`pull`, `diff`; default: latest) |
 | `--exclude <p1,p2>` | Extra exclude patterns (comma-separated) |
 | `--no-compress` | Disable gzip compression |
 | `--no-seal` | Create a new vector public (no Seal encryption). Only applies when creating; ignored for existing vectors |
@@ -57,7 +58,7 @@ Supply a signing key in one of three ways (checked in order):
 2. `--phrase "word1 word2 ..."`
 3. `WDOUBLESYNC_KEY` environment variable
 
-`pull` and `info` work without a key for public (unencrypted) vectors. A key is required for Seal-encrypted vectors and for any `push`.
+`pull`, `info` and `diff` work without a key for public (unencrypted) vectors. A key is required for Seal-encrypted vectors and for any `push`.
 
 ## Examples
 
@@ -113,6 +114,29 @@ wdoublesync info 0xabc123... --chain testnet
 wdoublesync info 0xabc123... ~/my-project --chain testnet
 ```
 
+### See what changed locally (diff)
+
+```bash
+# list files added/modified/deleted locally compared to the latest on-chain version
+wdoublesync diff 0xabc123... --chain testnet
+wdoublesync diff 0xabc123... ~/my-project --chain testnet
+
+# compare against a specific version
+wdoublesync diff 0xabc123... --chain testnet --version 2
+```
+
+Output shows the changes from the local folder's perspective — what a `push` would apply:
+
+```
+diff: ~/my-project vs 0xabc123... (version 3 of 3)
+local changes vs chain (what push would apply):
+  added:      docs/new-page.md
+  modified:   src/index.js
+  deleted:    old-config.json
+
+  3 change(s): 1 added, 1 modified, 1 deleted
+```
+
 ### Fast incremental pushes with a manifest
 
 ```bash
@@ -171,8 +195,9 @@ wdoublesync push 0xabc123... --chain testnet --key suiprivkey1... --force-snapsh
 1. **push** — scans the current directory, computes a tree hash, and compares it against the last stored version. If changes are detected, a compressed diff (or full snapshot on the first push) is uploaded to Walrus and appended to the EndlessVector on-chain.
 2. **pull** — reads the requested version from the EndlessVector, decrypts it if Seal-encrypted, and writes only changed files to disk. Files absent from the stored version are deleted.
 3. **info** — reads EndlessVector metadata from the chain (version count, binary size, history) and checks whether the local folder matches any stored version.
-4. **watch** — combines push and pull in a loop. A filesystem watcher triggers a debounced push on local changes. A poll interval checks the remote vector for new versions and pulls them if found. Push and pull never run concurrently.
-5. **rebate** — burns all existing archive patches on-chain and pushes the current folder as a single fresh full snapshot, reducing Walrus storage costs after many incremental syncs.
+4. **diff** — restores the requested version in memory (nothing is written to disk), hashes every file on both sides, and lists files added, modified, or deleted locally compared to the on-chain version.
+5. **watch** — combines push and pull in a loop. A filesystem watcher triggers a debounced push on local changes. A poll interval checks the remote vector for new versions and pulls them if found. Push and pull never run concurrently.
+6. **rebate** — burns all existing archive patches on-chain and pushes the current folder as a single fresh full snapshot, reducing Walrus storage costs after many incremental syncs.
 
 ### Default excludes
 

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: wdoublesync
-version: 0.1.8
-description: Claude agent skill for decentralized file storage, versioning, and sync on Sui + Walrus + Seal. Enables agents to push local folders as on-chain vectors, pull versions, manage Walrus storage, and watch for changes.
+version: 0.1.9
+description: Agent skill for decentralized file storage, versioning, and sync on Sui + Walrus + Seal. Enables agents to push local folders as on-chain vectors, pull versions, manage Walrus storage, and watch for changes.
 keywords: [walrus, sui, storage, versioning, sync, seal-encryption, blockchain, defi]
 ---
 
@@ -97,6 +97,7 @@ wdoublesync watch 0x1234... ~/my-data --poll-interval 5
 | **push** | `[vectorId]` `[path]` `[options]` | Sync folder to vector; creates new vector if no ID given |
 | **pull** | `vectorId` `[path]` `[options]` | Restore vector (default: latest version) into folder |
 | **info** | `[vectorId]` `[path]` | No ID: show chain + wallet. With ID: full vector details |
+| **diff** | `vectorId` `[path]` `[options]` | List files added/modified/deleted locally vs the on-chain version (read-only, writes nothing) |
 | **watch** | `vectorId` `[path]` `[options]` | Bi-directional sync: auto-push local changes, auto-pull remote updates |
 | **rebate** | `vectorId` `[path]` | Burn archive patches, push folder as fresh single snapshot |
 
@@ -150,6 +151,19 @@ wdoublesync pull 0x1234... ~/restored
 wdoublesync pull 0x1234... ~/restored --version 10
 ```
 
+#### diff (preview local changes before pushing)
+
+```bash
+wdoublesync diff 0x1234... ~/my-data
+# Output: local changes vs chain (what push would apply):
+#           added:      docs/new-page.md
+#           modified:   src/index.js
+#           deleted:    old-config.json
+#         3 change(s): 1 added, 1 modified, 1 deleted
+# Compare against an older version with --version N
+# Prints "no changes" when local matches the chain. Writes nothing to disk.
+```
+
 #### watch (bi-directional)
 
 ```bash
@@ -187,7 +201,7 @@ wdoublesync rebate 0x1234... ~/my-data
 | `--no-seal` | — | — | Push: create a new vector public (no Seal encryption). Only applies when creating a vector; ignored for existing ones |
 | `--manifest` | — | — | Push: write/use `.wdoublesync` file for faster change detection |
 | `--force-snapshot` | — | — | Push: full snapshot (repairs corrupt vectors) |
-| `--version` | Number | `latest` | Pull: restore specific version instead of latest |
+| `--version` | Number | `latest` | Pull/diff: use a specific version instead of latest |
 | `--exclude` | Patterns (comma-separated) | — | Extra file patterns to exclude from sync |
 | `--poll-interval` | Seconds | `2` | Watch: check for remote updates every N seconds |
 | `--debounce` | Milliseconds | `1000` | Watch: quiet period before pushing after local change |

package/bin/wdoublesync.js

@@ -11,7 +11,7 @@ process.exit = (code) => {
     throw err;
 };
 
-import { push, pull, info, watch, rebate } from '../lib/commands/index.js';
+import { push, pull, info, diff, watch, rebate } from '../lib/commands/index.js';
 
 const USAGE = `wdoublesync — sync local folders to EndlessVector on Sui+Walrus
 
@@ -19,6 +19,7 @@ Usage:
   wdoublesync push [vector-id] [options]   Sync current folder to vector (creates if no id)
   wdoublesync pull <vector-id> [options]   Restore vector contents to current folder
   wdoublesync info <vector-id> [options]   Show vector metadata
+  wdoublesync diff <vector-id> [options]   List local files added/modified/deleted vs the on-chain version
   wdoublesync watch <vector-id> [options]  Watch folder and auto-push/pull
   wdoublesync rebate <vector-id> [options] Archive history, burn archives, push fresh snapshot
 
@@ -26,7 +27,7 @@ Options:
   --chain <name>            Chain: mainnet, testnet, devnet, localnet (default: testnet)
   --key <suiprivkey>        Sui private key (or set WDOUBLESYNC_KEY env var)
   --phrase <mnemonic>       Mnemonic phrase
-  --version <n>             Version to restore (pull only, default: latest)
+  --version <n>             Version to restore/compare (pull, diff; default: latest)
   --exclude <p1,p2>         Extra exclude patterns (comma-separated)
   --no-compress             Disable gzip compression
   --no-seal                 Create a new vector public (no Seal encryption); only applies on creation
@@ -138,6 +139,8 @@ try {
         await pull(args);
     } else if (args.command === 'info') {
         await info(args);
+    } else if (args.command === 'diff') {
+        await diff(args);
     } else if (args.command === 'watch') {
         await watch(args);
     } else if (args.command === 'rebate') {

package/lib/WalrusSealClient.js

@@ -4,6 +4,10 @@ import { SuiGrpcClient, GrpcWebFetchTransport } from '@mysten/sui/grpc';
 import { Transaction } from '@mysten/sui/transactions';
 import { fromHex } from '@mysten/sui/utils';
 
+// Mysten's mainnet Seal committee key server requires an API key.
+const MAINNET_SEAL_API_KEY_NAME = 'x-api-key';
+const MAINNET_SEAL_API_KEY = 'c2f9b915-a4f3-41a2-bf91-99a630894db3';
+
 class WalrusSealClient {
 	/** @type {SuiGrpcClient} */
 	suiClient;
@@ -156,10 +160,12 @@ class WalrusSealClient {
 					{ objectId: '0xf5d14a81a982144ae441cd7d64b09027f116a468bd36e7eca494f750591623c8', weight: 1 },
 				],
 				mainnet: [
-					{ 
-					  objectId: '0x686098f1439237fff9f36b99c7329683c22979d2005c2465cb891acb012a7595', 
+					{
+						objectId: '0x686098f1439237fff9f36b99c7329683c22979d2005c2465cb891acb012a7595',
 						weight: 1,
-						aggregatorUrl: "https://seal-aggregator-mainnet.mystenlabs.com",
+						aggregatorUrl: 'https://seal-aggregator-mainnet.mystenlabs.com',
+						apiKeyName: MAINNET_SEAL_API_KEY_NAME,
+						apiKey: MAINNET_SEAL_API_KEY,
 					},
 				],
 			};

package/lib/commands/diff.js

@@ -0,0 +1,114 @@
+import EndlessVector from '@fizzyflow/endless-vector';
+import { WDoubleSync } from '@fizzyflow/wdoublesync';
+import { DoubleSyncFSFolder } from '../DoubleSyncFSFolder.js';
+import {
+    makeClientForRead,
+    resolvePath,
+    makeExcludes,
+    formatPath,
+    hashLocalTree,
+} from './shared.js';
+
+export function compareFileMaps(localFiles, remoteFiles) {
+    const added = [];
+    const modified = [];
+    const deleted = [];
+
+    for (const path of Object.keys(localFiles)) {
+        if (!(path in remoteFiles)) {
+            added.push(path);
+        } else if (localFiles[path] !== remoteFiles[path]) {
+            modified.push(path);
+        }
+    }
+    for (const path of Object.keys(remoteFiles)) {
+        if (!(path in localFiles)) {
+            deleted.push(path);
+        }
+    }
+
+    added.sort();
+    modified.sort();
+    deleted.sort();
+
+    return { added, modified, deleted };
+}
+
+export async function diff(args) {
+    if (!args.vectorId) {
+        throw new Error('vector-id is required for diff');
+    }
+
+    const wsc = await makeClientForRead(args);
+
+    const evParams = {
+        suiClient: wsc.suiClient,
+        id: args.vectorId,
+        packageId: args.chain,
+        walrusClient: wsc.walrusClient,
+        aggregatorUrl: wsc.aggregatorUrl,
+    };
+    if (wsc.sealClient && wsc.suiMaster) {
+        evParams.sealClient = wsc.sealClient;
+        evParams.signAndExecuteTransaction = (tx) => wsc.signAndExecuteTransaction(tx);
+        evParams.senderAddress = wsc.suiMaster.address;
+        evParams.signer = wsc.suiMaster._keypair;
+    }
+
+    const ev = new EndlessVector(evParams);
+    const wdsync = new WDoubleSync({ endlessVector: ev });
+
+    await ev.initialize();
+    const totalVersions = ev.length;
+
+    if (totalVersions === 0) {
+        console.log('vector', args.vectorId, 'has no versions yet — nothing to diff');
+        return;
+    }
+
+    const version = args.version != null ? Number(args.version) : totalVersions;
+    if (!Number.isInteger(version) || version < 1 || version > totalVersions) {
+        throw new Error('version must be between 1 and ' + totalVersions);
+    }
+
+    const destPath = resolvePath(args.path);
+    console.log('diff:', formatPath(destPath), 'vs', args.vectorId, '(version ' + version + ' of ' + totalVersions + ')');
+    console.log('  restoring chain version...');
+
+    let remoteFolder;
+    try {
+        remoteFolder = await wdsync.restore(version === totalVersions ? undefined : version);
+    } catch (err) {
+        if (err.message?.includes('sealClient not configured') || err.message?.includes('signer or sessionKey is required')) {
+            throw new Error('This vector is Seal-encrypted. Provide --key or --phrase to decrypt.');
+        }
+        throw err;
+    }
+
+    const remoteFiles = await hashLocalTree(remoteFolder);
+    const fsFolder = new DoubleSyncFSFolder(destPath, makeExcludes(args));
+    let localFiles = {};
+    try {
+        localFiles = await hashLocalTree(fsFolder);
+    } catch {
+        // local folder missing or unreadable — treat as empty
+    }
+
+    const { added, modified, deleted } = compareFileMaps(localFiles, remoteFiles);
+    const total = added.length + modified.length + deleted.length;
+
+    if (total === 0) {
+        console.log('  no changes — local folder matches version', version);
+        return;
+    }
+
+    console.log('\nlocal changes vs chain (what push would apply):');
+    for (const path of added) console.log('  added:     ', path);
+    for (const path of modified) console.log('  modified:  ', path);
+    for (const path of deleted) console.log('  deleted:   ', path);
+
+    console.log('\n  ' + total + ' change(s): ' +
+        added.length + ' added, ' +
+        modified.length + ' modified, ' +
+        deleted.length + ' deleted');
+}

package/lib/commands/index.js

@@ -1,5 +1,6 @@
 export { push } from './push.js';
 export { pull } from './pull.js';
 export { info } from './info.js';
+export { diff } from './diff.js';
 export { watch } from './watch.js';
 export { rebate } from './rebate.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fizzyflow/wdoublesync_cli",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "type": "module",
   "description": "CLI tool built on the wdoublesync library to sync local folders to Walrus decentralised storage on the Sui network. Stores versioned gzip-compressed snapshots and diffs inside an EndlessVector on-chain object. Supports Seal encryption, manifest-based fast change detection, and full version history with point-in-time restore.",
   "bin": {
@@ -11,11 +11,13 @@
   },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
-    "pull:test": "mkdir -p test_pull && cd test_pull && node ../bin/wdoublesync.js pull 0x69d7d77c55d66c4c6d0a87d120caf0535fdbb3c8c414658f81f66a4d50c80120 --chain testnet",
-    "push:test": "cd test_pull && node ../bin/wdoublesync.js push 0x69d7d77c55d66c4c6d0a87d120caf0535fdbb3c8c414658f81f66a4d50c80120 --chain testnet",
-    "pushfull:test": "cd test_pull && node ../bin/wdoublesync.js push 0x69d7d77c55d66c4c6d0a87d120caf0535fdbb3c8c414658f81f66a4d50c80120 --chain testnet --force-snapshot",
-    "info:test": "cd test_pull && node ../bin/wdoublesync.js info 0x69d7d77c55d66c4c6d0a87d120caf0535fdbb3c8c414658f81f66a4d50c80120 --chain testnet",
-    "watch:test": "cd test_pull && node ../bin/wdoublesync.js watch 0x69d7d77c55d66c4c6d0a87d120caf0535fdbb3c8c414658f81f66a4d50c80120 --chain testnet"
+    "pushnew:test": "cd test_pull && node ../bin/wdoublesync.js push --chain mainnet",
+    "pull:test": "mkdir -p test_pull && cd test_pull && node ../bin/wdoublesync.js pull 0x77f779ed40404203406f1854bb7dd183fbc4743d28beb056057823c6b2b565c0 --chain mainnet",
+    "push:test": "cd test_pull && node ../bin/wdoublesync.js push 0x77f779ed40404203406f1854bb7dd183fbc4743d28beb056057823c6b2b565c0 --chain mainnet",
+    "pushfull:test": "cd test_pull && node ../bin/wdoublesync.js push 0x77f779ed40404203406f1854bb7dd183fbc4743d28beb056057823c6b2b565c0 --chain mainnet --force-snapshot",
+    "info:test": "cd test_pull && node ../bin/wdoublesync.js info 0x77f779ed40404203406f1854bb7dd183fbc4743d28beb056057823c6b2b565c0 --chain mainnet",
+    "diff:test": "cd test_pull && node ../bin/wdoublesync.js diff 0x77f779ed40404203406f1854bb7dd183fbc4743d28beb056057823c6b2b565c0 --chain mainnet",
+    "watch:test": "cd test_pull && node ../bin/wdoublesync.js watch 0x77f779ed40404203406f1854bb7dd183fbc4743d28beb056057823c6b2b565c0 --chain mainnet"
   },
   "keywords": [],
   "author": "suidouble (https://github.com/suidouble)",