mnemonad-cli 0.1.0

package/lib/chainClient.js

@@ -0,0 +1,112 @@
+/**
+ * Monad's auth model is just a viem account, so no client wrapper class is needed here,
+ * only a couple of plain functions. Follows the exact pattern already established in
+ * `scripts/deploy.js` and `js/test/fixture.js`'s `makeClients()`: `viem/chains`'
+ * `monad`/`monadTestnet` + `privateKeyToAccount`/`mnemonicToAccount` +
+ * `createPublicClient`/`createWalletClient` with an `http()` transport.
+ */
+import { createPublicClient, createWalletClient, defineChain, http } from 'viem';
+import { privateKeyToAccount, mnemonicToAccount } from 'viem/accounts';
+import { monad, monadTestnet } from 'viem/chains';
+
+/**
+ * CLI `--chain` name -> { viem chain object, Mnemonad network shorthand for
+ * `contractAddress` }. The two disagree on the mainnet name for the same reason
+ * `scripts/deploy.js`'s own `IDS_KEY` map does: `monad` matches viem/chains, `monadMainnet`
+ * is what `js/ids.js` already uses — reconciled here rather than renaming either side.
+ */
+const CHAINS = {
+	testnet: { chain: monadTestnet, contractAddress: 'monadTestnet' },
+	mainnet: { chain: monad, contractAddress: 'monadMainnet' },
+};
+
+/**
+ * `--chain local` is not a real Mnemonad deployment — it's for running against a local
+ * Hardhat node (`js/test/fixture.js`'s own `startNode()`, same chain id 31337 that node
+ * defaults to), used by this package's own tests and by manual smoke-testing during
+ * development. Unlike `testnet`/`mainnet`, its viem chain object depends on `--rpc-url`
+ * (there's no fixed default endpoint for "some local node"), and it has no known
+ * `contractAddress` shorthand — the caller must always pass `--contract-address` for a
+ * freshly-deployed local registry, since `js/ids.js` only lists testnet/mainnet.
+ */
+function localChain(rpcUrl) {
+	if (!rpcUrl) {
+		throw new Error("--chain local requires --rpc-url pointing at the local node");
+	}
+	return defineChain({
+		id: 31337,
+		name: 'Hardhat',
+		nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+		rpcUrls: { default: { http: [rpcUrl] } },
+	});
+}
+
+function normalizeKey(key) {
+	return key.startsWith('0x') ? key : `0x${key}`;
+}
+
+function resolveAccount(args) {
+	const key = args.key || process.env.MNEMONAD_KEY;
+	if (key) return privateKeyToAccount(normalizeKey(key));
+	if (args.phrase) return mnemonicToAccount(args.phrase);
+	return null;
+}
+
+/**
+ * Resolves `--chain`/`--rpc-url` into a viem chain + the Mnemonad network shorthand
+ * `contractAddress` accepts directly, and `--key`/`--phrase`/`MNEMONAD_KEY` into an
+ * optional signing account. Never throws for a missing key — read-only commands (`pull`,
+ * `info`, `diff`) are fine without one; commands that need to sign call
+ * `requireWalletClient` themselves, so the "no key" error only surfaces where it's
+ * actually required.
+ *
+ * @param {Object} args - parsed CLI args: `chain`, `rpcUrl`, `key`, `phrase`, `contractAddress`
+ * @returns {{
+ *   publicClient: Object,
+ *   walletClient: ?Object,
+ *   account: ?Object,
+ *   contractAddress: string,
+ *   chain: Object,
+ * }}
+ */
+export function makeChainClient(args) {
+	let chain, contractAddress;
+	if (args.chain === 'local') {
+		// Dev/test only — see localChain() above.
+		chain = localChain(args.rpcUrl);
+		contractAddress = args.contractAddress;
+		if (!contractAddress) {
+			throw new Error('--chain local requires --contract-address (no known deployment to default to)');
+		}
+	} else {
+		const known = CHAINS[args.chain];
+		if (!known) {
+			throw new Error(`unknown --chain '${args.chain}', expected one of ${[...Object.keys(CHAINS), 'local'].join(', ')}`);
+		}
+		chain = known.chain;
+		// --contract-address overrides the network's own known deployment — mainly useful
+		// for pointing at a different/newer registry without needing a code change to
+		// js/ids.js first.
+		contractAddress = args.contractAddress || known.contractAddress;
+	}
+
+	// http(undefined) falls back to the chain's own default RPC URL — no need to clone or
+	// mutate the chain object just to point at a different endpoint.
+	const transport = http(args.rpcUrl);
+	const publicClient = createPublicClient({ chain, transport });
+
+	const account = resolveAccount(args);
+	const walletClient = account ? createWalletClient({ chain, transport, account }) : null;
+
+	return { publicClient, walletClient, account, contractAddress, chain };
+}
+
+/**
+ * Fails fast with an actionable message when a command needs to sign (push, watch with
+ * push enabled, compact) but no key was configured.
+ */
+export function requireWalletClient(client) {
+	if (!client.walletClient) {
+		throw new Error('No signing key. Use --key, --phrase, or MNEMONAD_KEY env var');
+	}
+}

package/lib/commands/compact.js

@@ -0,0 +1,85 @@
+import Mnemonad from 'mnemonad';
+import { MonadSync } from 'monadsync';
+import { FSFolder } from '../FSFolder.js';
+import { makeChainClient, requireWalletClient } from '../chainClient.js';
+import {
+    resolvePath,
+    makeExcludes,
+    formatBytes,
+    countTree,
+    assertStreamOwner,
+    unlockStream,
+    resolveOffloadParams,
+} from './shared.js';
+
+/**
+ * Monad has no rebate/refund concept — truncating a stream's history here gives back no
+ * gas, only a shorter replay for future `restore()`/`initialize()` calls. This drops old
+ * history, then forces a full snapshot, without pretending there's a cost refund attached
+ * to it.
+ */
+export async function compact(args) {
+    if (!args.streamId) {
+        throw new Error('stream-id is required for compact');
+    }
+
+    const destPath = resolvePath(args.path);
+    const fsFolder = new FSFolder(destPath, makeExcludes(args));
+
+    const counts = await countTree(fsFolder);
+    console.log('  scanning...', counts.files, 'files,', counts.folders, 'folders');
+
+    const client = makeChainClient(args);
+    requireWalletClient(client);
+
+    // No `password` at construction — see shared.js's unlockStream() for why.
+    const mn = new Mnemonad({
+        publicClient: client.publicClient,
+        walletClient: client.walletClient,
+        contractAddress: client.contractAddress,
+        id: args.streamId,
+        ...resolveOffloadParams(args, client.account),
+    });
+
+    await assertStreamOwner(mn, client.account.address);
+    await unlockStream(mn, { password: args.password, signer: client.walletClient });
+
+    console.log('step 1: truncating existing history...');
+    const droppedCount = mn.length - mn.firstAvailableIndex;
+    if (droppedCount > 0) {
+        // Drops everything up to (not including) the stream's current length — the
+        // upcoming full-snapshot push becomes the new sole baseline for restore/replay.
+        await mn.truncateFrom(mn.length);
+        console.log('  dropped', droppedCount, 'history entries');
+    } else {
+        console.log('  nothing to drop (stream is empty)');
+    }
+
+    console.log('step 2: pushing local state as fresh snapshot...');
+
+    const monadSync = new MonadSync({ mnemonad: mn, compress: args.compress || 'gzip' });
+
+    // Skip monadSync's own replay entirely: compact always pushes a full snapshot, so
+    // there's nothing to replay against. Same escape hatch monadsync/README.md's
+    // "Repairing a corrupt chain" section documents.
+    mn.reInitialize();
+    await mn.initialize();
+    monadSync._isInitialized = true;
+    monadSync._lastSnapshot = null;
+    monadSync._replayedCount = mn.length;
+
+    const result = await monadSync.push(fsFolder);
+
+    mn.reInitialize();
+    await mn.initialize();
+
+    console.log('  pushed version', result.version);
+
+    console.log('\ncompact complete:');
+    console.log('  new version:      ', result.version);
+    console.log('  new on-chain size:', formatBytes(mn.binaryLength));
+    if (droppedCount > 0) {
+        console.log('  future restore()/initialize() no longer replay the', droppedCount, 'dropped entries —',
+            'faster reads, not a cost refund.');
+    }
+}

package/lib/commands/diff.js

@@ -0,0 +1,112 @@
+import Mnemonad from 'mnemonad';
+import { MonadSync } from 'monadsync';
+import { FSFolder } from '../FSFolder.js';
+import { makeChainClient } from '../chainClient.js';
+import {
+    resolvePath,
+    makeExcludes,
+    formatPath,
+    hashLocalTree,
+    unlockStream,
+} 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.streamId) {
+        throw new Error('stream-id is required for diff');
+    }
+    // Resolved up front (throws if missing) so a missing path fails fast, before any chain
+    // work — see resolvePath()'s own comment for why this is never defaulted to cwd.
+    const destPath = resolvePath(args.path);
+
+    const client = makeChainClient(args);
+
+    const mn = new Mnemonad({
+        publicClient: client.publicClient,
+        walletClient: client.walletClient,
+        contractAddress: client.contractAddress,
+        id: args.streamId,
+        gatewayUrl: args.gatewayUrl,
+    });
+    const monadSync = new MonadSync({ mnemonad: mn });
+
+    // See shared.js's unlockStream() for why `password` isn't passed to the constructor
+    // above — this fetches the stream's own already-published salt instead of deriving a
+    // key from a fresh one.
+    await unlockStream(mn, { password: args.password, signer: client.walletClient });
+    const totalVersions = mn.length;
+
+    if (totalVersions === 0) {
+        console.log('stream', args.streamId, '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);
+    }
+
+    console.log('diff:', formatPath(destPath), 'vs', args.streamId, '(version ' + version + ' of ' + totalVersions + ')');
+    console.log('  restoring chain version...');
+
+    let remoteFolder;
+    try {
+        remoteFolder = await monadSync.restore(version === totalVersions ? undefined : version);
+    } catch (err) {
+        if (err.code === 'KEK_MISMATCH' || err.message?.includes('decrypt') || err.message?.includes('invalid tag')) {
+            throw new Error('Could not decrypt this stream: ' + err.message);
+        }
+        throw err;
+    }
+
+    const remoteFiles = await hashLocalTree(remoteFolder);
+    const fsFolder = new FSFolder(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

@@ -0,0 +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 { compact } from './compact.js';

package/lib/commands/info.js

@@ -0,0 +1,123 @@
+import Mnemonad, { kekMethodOf } from 'mnemonad';
+import { MonadSync } from 'monadsync';
+import { makeChainClient } from '../chainClient.js';
+import {
+    resolvePath,
+    formatBytes,
+    localTreeHash,
+    unlockStream,
+} from './shared.js';
+
+export async function info(args) {
+    const client = makeChainClient(args);
+
+    console.log('  chain:          ', args.chain);
+    console.log('  your wallet:    ', client.account?.address || '(none)');
+
+    if (!args.streamId) {
+        return;
+    }
+
+    // No `password` passed to the constructor — see shared.js's unlockStream() for why:
+    // this instance doesn't yet know whether the stream is even encrypted, let alone its
+    // published salt, so it's unlocked explicitly below once isEncrypted() is known.
+    const mn = new Mnemonad({
+        publicClient: client.publicClient,
+        walletClient: client.walletClient,
+        contractAddress: client.contractAddress,
+        id: args.streamId,
+        gatewayUrl: args.gatewayUrl,
+    });
+
+    await mn.initialize();
+
+    const totalVersions = mn.length;
+
+    console.log('\nstream:', args.streamId);
+
+    const owner = await mn.owner().catch(() => null) || '(unknown)';
+    const isOwner = client.account && owner !== '(unknown)' && client.account.address.toLowerCase() === owner.toLowerCase();
+
+    const isEncrypted = await mn.isEncrypted();
+    const kekMethod = kekMethodOf({ kek: mn.streamMeta.kek, encrypted: isEncrypted });
+    // Unlike pull/diff (which have nothing useful to do at all without decrypting), info
+    // still has metadata worth showing on a stream it can't open — so this unlocks when the
+    // right credential happens to be at hand and otherwise just notes it, rather than
+    // throwing. `unlocked` then gates the local-version comparison further down.
+    let unlocked = false;
+    if (isEncrypted) {
+        try {
+            unlocked = await unlockStream(mn, { password: args.password, signer: client.walletClient });
+        } catch {
+            // Missing or wrong credential — reported below, not fatal for `info`.
+        }
+    }
+    console.log('  owner:          ', isOwner ? owner + ' (you)' : owner);
+    console.log(
+        '  encrypted:      ',
+        isEncrypted ? (kekMethod === 'password' ? 'yes (password)' : 'yes (owner wallet)') : 'no'
+    );
+    console.log('  versions:       ', totalVersions);
+    console.log('  binary size:    ', formatBytes(mn.binaryLength));
+    if (mn.firstAvailableIndex > 0) {
+        console.log('  history starts: ', 'index', mn.firstAvailableIndex, '(earlier history truncated — see `compact`)');
+    }
+
+    const destPath = resolvePath(args.path);
+    const localHash = await localTreeHash(destPath);
+
+    if (!localHash) {
+        console.log('\n  local folder:    empty (run pull to fetch)');
+        return;
+    }
+
+    // Same reasoning as pull.js/diff.js: an un-unlocked stream decrypts to nothing useful,
+    // so the tree-hash detection loop below would only ever compare garbage against garbage
+    // — better to say what's missing up front and stop.
+    if (isEncrypted && !unlocked) {
+        console.log(
+            kekMethod === 'password'
+                ? '\n  (encrypted — provide --password to compare against the local folder)'
+                : '\n  (encrypted to the owner\'s wallet — provide their --key / --phrase to\n' +
+                  '   compare against the local folder)'
+        );
+        return;
+    }
+
+    const localHex = Buffer.from(localHash).toString('hex').slice(0, 12);
+    console.log('\n  local tree hash: ', localHex + '...');
+    console.log('  detecting local version...');
+
+    const monadSync = new MonadSync({ mnemonad: mn });
+    let matchedVersion = null;
+
+    for (let v = totalVersions; v >= Math.max(mn.firstAvailableIndex, 1); v--) {
+        process.stdout.write('  checking version ' + v + '/' + totalVersions + '...          \r');
+        let remoteHash;
+        try {
+            remoteHash = await monadSync.getTreeHash(v);
+        } catch (err) {
+            if (err.code === 'KEK_MISMATCH' || err.message?.includes('decrypt') || err.message?.includes('invalid tag')) {
+                throw new Error('Could not decrypt this stream: ' + err.message);
+            }
+            throw err;
+        }
+        if (localHash.length === remoteHash.length && localHash.every((b, i) => b === remoteHash[i])) {
+            matchedVersion = v;
+            break;
+        }
+    }
+
+    process.stdout.write('                                                \r');
+    if (matchedVersion !== null) {
+        console.log('  local matches:   version', matchedVersion, 'of', totalVersions);
+        if (matchedVersion < totalVersions) {
+            console.log('  behind by:      ', totalVersions - matchedVersion, 'version(s)');
+        } else {
+            console.log('  status:          up to date');
+        }
+    } else {
+        console.log('  local matches:   no known version (local modifications?)');
+        console.log('  latest remote:   version', totalVersions);
+    }
+}

package/lib/commands/pull.js

@@ -0,0 +1,64 @@
+import Mnemonad from 'mnemonad';
+import { MonadSync } from 'monadsync';
+import { makeChainClient } from '../chainClient.js';
+import {
+    resolvePath,
+    formatBytes,
+    hashDiskTree,
+    syncMemoryFolderToDisk,
+    writeManifest,
+    unlockStream,
+} from './shared.js';
+
+export async function pull(args) {
+    if (!args.streamId) {
+        throw new Error('stream-id is required for pull');
+    }
+    // Resolved up front (throws if missing) so a missing path fails fast, before any chain
+    // work — see resolvePath()'s own comment for why this is never defaulted to cwd.
+    const destPath = resolvePath(args.path);
+
+    const client = makeChainClient(args);
+
+    const mn = new Mnemonad({
+        publicClient: client.publicClient,
+        walletClient: client.walletClient,
+        contractAddress: client.contractAddress,
+        id: args.streamId,
+        gatewayUrl: args.gatewayUrl,
+    });
+    const monadSync = new MonadSync({ mnemonad: mn });
+
+    // See unlockStream()'s own comment for why `password` isn't passed to the constructor
+    // above: reopening an existing encrypted stream needs its own already-published salt,
+    // which only unlockWithPassword() (called inside unlockStream) fetches correctly.
+    await unlockStream(mn, { password: args.password, signer: client.walletClient });
+
+    const version = args.version != null ? Number(args.version) : undefined;
+    console.log('restoring', args.streamId, version != null ? 'at version ' + version : '(latest)', '...');
+
+    let folder;
+    try {
+        folder = await monadSync.restore(version);
+    } catch (err) {
+        if (err.code === 'KEK_MISMATCH' || err.message?.includes('decrypt') || err.message?.includes('invalid tag')) {
+            // unlockStream() above already demanded the right *kind* of credential, so
+            // reaching here means the one supplied didn't actually open this stream.
+            throw new Error('Could not decrypt this stream: ' + err.message);
+        }
+        throw err;
+    }
+
+    const oldFiles = await hashDiskTree(destPath);
+
+    const { stats, newFiles } = await syncMemoryFolderToDisk(folder, destPath, oldFiles);
+
+    if (args.manifest) {
+        await mn.initialize();
+        const pulledVersion = version ?? mn.length;
+        await writeManifest(destPath, { streamId: args.streamId, version: pulledVersion, files: newFiles });
+    }
+
+    console.log(' ', stats.written, 'written,', stats.skipped, 'unchanged,',
+                stats.deleted, 'deleted', '(' + formatBytes(stats.bytes) + ')');
+}

package/lib/commands/push.js

@@ -0,0 +1,127 @@
+import Mnemonad from 'mnemonad';
+import { MonadSync } from 'monadsync';
+import { FSFolder } from '../FSFolder.js';
+import { makeChainClient, requireWalletClient } from '../chainClient.js';
+import {
+    resolvePath,
+    makeExcludes,
+    countTree,
+    localTreeHash,
+    readManifest,
+    writeManifest,
+    hashLocalTree,
+    hashMapsEqual,
+    assertStreamOwner,
+    unlockStream,
+    resolveEncryptMethod,
+    resolveOffloadParams,
+} from './shared.js';
+
+export async function push(args) {
+    let streamId = args.streamId;
+
+    const destPath = resolvePath(args.path);
+    const fsFolder = new FSFolder(destPath, makeExcludes(args));
+
+    const counts = await countTree(fsFolder);
+    console.log('  scanning...', counts.files, 'files,', counts.folders, 'folders');
+
+    if (args.manifest) {
+        const manifest = await readManifest(destPath);
+        const localFiles = await hashLocalTree(fsFolder);
+        if (streamId && manifest && manifest.streamId === streamId && manifest.files) {
+            if (hashMapsEqual(localFiles, manifest.files)) {
+                console.log('  no changes since last pull, nothing to push');
+                return;
+            }
+        }
+    }
+
+    const client = makeChainClient(args);
+    requireWalletClient(client);
+
+    const baseParams = {
+        publicClient: client.publicClient,
+        walletClient: client.walletClient,
+        contractAddress: client.contractAddress,
+        ...resolveOffloadParams(args, client.account),
+    };
+
+    // Validated up front, so a bad flag combination fails before any chain work — including
+    // on the push-to-existing path, where the encryption flags don't apply at all.
+    const encryptMethod = resolveEncryptMethod(args);
+
+    let mn;
+    if (!streamId) {
+        // The credential is only ever passed to the constructor *here*, on the instance
+        // calling `create()` itself: it generates and publishes whatever a later reader needs
+        // (a password salt, or the method marker), so there's nothing existing to fetch. See
+        // unlockStream()'s own comment for why every other path must NOT do this.
+        const createParams = { ...baseParams };
+        if (encryptMethod === 'password') {
+            createParams.encrypt = true;
+            createParams.password = args.password;
+        } else if (encryptMethod === 'wallet') {
+            createParams.encrypt = true;
+            // The same account that signs the create transaction also signs for the key —
+            // so this asks the wallet twice, and only this account can ever decrypt it.
+            createParams.signer = client.walletClient;
+        }
+        const how = encryptMethod === 'password' ? '(encrypted with a password)'
+            : encryptMethod === 'wallet' ? '(encrypted to ' + client.account.address + ')'
+            : '(public)';
+        console.log('creating new stream on', args.chain, how, '...');
+        mn = await Mnemonad.create(createParams);
+        streamId = mn.id.toString();
+        console.log('  created:', streamId);
+    } else {
+        mn = new Mnemonad({ ...baseParams, id: streamId });
+        await assertStreamOwner(mn, client.account.address);
+        await unlockStream(mn, { password: args.password, signer: client.walletClient });
+        if (args.encrypt) {
+            console.log('  note: --encrypt only applies when creating a new stream; pushing to an existing stream keeps its current encryption');
+        }
+    }
+
+    console.log('syncing ./ →', streamId);
+
+    const monadSync = new MonadSync({ mnemonad: mn, compress: args.compress || 'gzip' });
+
+    let existingVersions = 0;
+    if (args.forceSnapshot) {
+        console.log('  skipping chain replay — pushing full snapshot...');
+        await mn.initialize();
+        // See monadsync/README.md's "Repairing a corrupt chain" section — this is the
+        // documented escape hatch for forcing a full snapshot instead of a diff.
+        monadSync._isInitialized = true;
+        monadSync._lastSnapshot = null;
+        monadSync._replayedCount = mn.length;
+    } else {
+        await monadSync.initialize();
+        existingVersions = await monadSync.length();
+
+        if (streamId && existingVersions > 0 && !args.manifest) {
+            console.log('  comparing tree hashes...');
+            const localHash = await localTreeHash(destPath);
+            const remoteHash = await monadSync.getTreeHash(existingVersions);
+            if (localHash && remoteHash.length === localHash.length &&
+                localHash.every((b, i) => b === remoteHash[i])) {
+                console.log('  no changes, nothing to push');
+                return;
+            }
+        }
+    }
+
+    console.log('  building patch + pushing to chain...');
+    const result = await monadSync.push(fsFolder);
+
+    const patchType = args.forceSnapshot || existingVersions === 0 ? 'full snapshot' : 'diff';
+    const compressedNote = args.compress !== false ? ', gzip compressed' : '';
+    console.log('  version', result.version, 'pushed (' + patchType + compressedNote + ')');
+    console.log('  stream:', streamId);
+
+    if (args.manifest) {
+        const localFiles = await hashLocalTree(fsFolder);
+        await writeManifest(destPath, { streamId, version: result.version, files: localFiles });
+    }
+}