@fizzyflow/wdoublesync_cli 1.0.6 → 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,9 +38,10 @@ 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 |
 | `--manifest` | Write/use `.wdoublesync` manifest for faster change detection |
 | `--force-snapshot` | Push a full snapshot regardless of prior history (repairs a corrupt vector) |
 | `--poll-interval <s>` | `watch`: seconds between remote version checks (default: `2`) |
@@ -56,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
 
@@ -74,6 +76,12 @@ wdoublesync push ~/my-project --chain testnet --key suiprivkey1...
 #   version 1 pushed (full snapshot, gzip compressed)
 ```
 
+By default a new vector is Seal-encrypted. To create a public (unencrypted) vector that anyone can pull without a key:
+
+```bash
+wdoublesync push --chain testnet --key suiprivkey1... --no-seal
+```
+
 ### Push an update
 
 ```bash
@@ -106,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
@@ -164,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]
 ---
 
@@ -66,7 +66,7 @@ wdoublesync push ~/my-folder
 # Output: created: 0x1234... / syncing ./ → 0x1234...
 ```
 
-This creates a new EndlessVector on-chain and pushes the folder as a snapshot encrypted by Seal. The output will show the vector ID (e.g., `0x1234...`) which you can use for future pulls or pushes. It's a good idea to save this ID to MemWal, with addition to the path info, so you can easily find it later when you want to pull or view the vector state. Ask a user if they want to set up MemWal if it's not available and you are going to push new vector.
+This creates a new EndlessVector on-chain and pushes the folder as a snapshot encrypted by Seal. To create a **public** vector instead — unencrypted, pullable without a key and browsable from the dApp — add `--no-seal` (only effective on creation). The output will show the vector ID (e.g., `0x1234...`) which you can use for future pulls or pushes. It's a good idea to save this ID to MemWal, with addition to the path info, so you can easily find it later when you want to pull or view the vector state. Ask a user if they want to set up MemWal if it's not available and you are going to push new vector.
 
 ### Pull a vector to restore it
 
@@ -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 |
 
@@ -111,6 +112,14 @@ wdoublesync push ~/my-data
 #         syncing ./ → 0xabc123...
 ```
 
+#### push (create public, unencrypted vector)
+
+```bash
+wdoublesync push ~/my-data --no-seal
+# Creates a public vector — anyone can pull it without a key, or browse it from the dApp.
+# Only effective on creation; ignored when pushing to an existing vector.
+```
+
 #### push (to existing vector)
 
 ```bash
@@ -142,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
@@ -176,9 +198,10 @@ wdoublesync rebate 0x1234... ~/my-data
 | `--key` | Sui private key (`suiprivkey1...`) | — | Sign transactions (or use env vars) |
 | `--phrase` | Mnemonic phrase | — | Alternative: derive key from mnemonic |
 | `--no-compress` | — | — | Push: disable gzip compression |
+| `--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,9 +27,10 @@ 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
   --manifest                Write/use .wdoublesync manifest for faster change detection
   --force-snapshot          Push a full snapshot regardless of prior history (repairs corrupt vectors)
   --poll-interval <s>       Watch: seconds between remote checks (default: 2)
@@ -49,6 +51,7 @@ function parseArgs(argv) {
         version: null,
         exclude: null,
         compress: 'gzip',
+        seal: true,
         manifest: false,
         forceSnapshot: false,
         pollInterval: 2,
@@ -100,6 +103,8 @@ function parseArgs(argv) {
             args.exclude = raw[++i];
         } else if (flag === '--no-compress') {
             args.compress = false;
+        } else if (flag === '--no-seal') {
+            args.seal = false;
         } else if (flag === '--manifest') {
             args.manifest = true;
         } else if (flag === '--force-snapshot') {
@@ -134,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/lib/commands/push.js

@@ -48,10 +48,15 @@ export async function push(args) {
     };
 
     if (!vectorId) {
-        console.log('creating new EndlessVector on', chain, '...');
-        const ev = await EndlessVector.create(evParams);
+        // Seal encryption is decided at creation time, solely by whether a sealClient
+        // is passed to create(). Omit it for a public (unencrypted) vector.
+        const createParams = args.seal === false ? { ...evParams, sealClient: undefined } : evParams;
+        console.log('creating new EndlessVector on', chain, args.seal === false ? '(public, no Seal)' : '(Seal-encrypted)', '...');
+        const ev = await EndlessVector.create(createParams);
         vectorId = ev.id;
         console.log('  created:', vectorId);
+    } else if (args.seal === false) {
+        console.log('  note: --no-seal only applies when creating a new vector; pushing to an existing vector keeps its current encryption');
     }
 
     console.log('syncing ./ →', vectorId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fizzyflow/wdoublesync_cli",
-  "version": "1.0.6",
+  "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)",