mnemonad-cli 0.1.1 → 0.3.0

package/lib/chainClient.js

@@ -8,6 +8,8 @@
 import { createPublicClient, createWalletClient, defineChain, http } from 'viem';
 import { privateKeyToAccount, mnemonicToAccount } from 'viem/accounts';
 import { monad, monadTestnet } from 'viem/chains';
+import { openPasskeyBridge } from './passkeyBridge.js';
+import { userError } from './commands/shared.js';
 
 /**
  * CLI `--chain` name -> { viem chain object, Mnemonad network shorthand for
@@ -45,10 +47,20 @@ function normalizeKey(key) {
 	return key.startsWith('0x') ? key : `0x${key}`;
 }
 
-function resolveAccount(args) {
+/**
+ * `--key`/`--phrase`/`MNEMONAD_KEY` resolve synchronously; `--passkey` doesn't (it opens a
+ * browser tab and waits for a human to complete a WebAuthn prompt) — see
+ * passkeyBridge.js. That's the one thing that makes this function, and therefore
+ * `makeChainClient`, async rather than the plain synchronous lookup it used to be.
+ */
+async function resolveAccount(args) {
 	const key = args.key || process.env.MNEMONAD_KEY;
+	if (args.passkey && (key || args.phrase)) {
+		throw userError('--passkey cannot be combined with --key/--phrase/MNEMONAD_KEY — pick one signing method.');
+	}
 	if (key) return privateKeyToAccount(normalizeKey(key));
 	if (args.phrase) return mnemonicToAccount(args.phrase);
+	if (args.passkey) return openPasskeyBridge(args);
 	return null;
 }
 
@@ -60,16 +72,17 @@ function resolveAccount(args) {
  * `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 {{
+ * @param {Object} args - parsed CLI args: `chain`, `rpcUrl`, `key`, `phrase`, `passkey`,
+ *   `authOrigin`, `contractAddress`
+ * @returns {Promise<{
  *   publicClient: Object,
  *   walletClient: ?Object,
  *   account: ?Object,
  *   contractAddress: string,
  *   chain: Object,
- * }}
+ * }>}
  */
-export function makeChainClient(args) {
+export async function makeChainClient(args) {
 	let chain, contractAddress;
 	if (args.chain === 'local') {
 		// Dev/test only — see localChain() above.
@@ -95,7 +108,7 @@ export function makeChainClient(args) {
 	const transport = http(args.rpcUrl);
 	const publicClient = createPublicClient({ chain, transport });
 
-	const account = resolveAccount(args);
+	const account = await resolveAccount(args);
 	const walletClient = account ? createWalletClient({ chain, transport, account }) : null;
 
 	return { publicClient, walletClient, account, contractAddress, chain };
@@ -107,6 +120,14 @@ export function makeChainClient(args) {
  */
 export function requireWalletClient(client) {
 	if (!client.walletClient) {
-		throw new Error('No signing key. Use --key, --phrase, or MNEMONAD_KEY env var');
+		// Marked as a user error so the CLI boundary prints the message alone: this is the
+		// first thing anyone hits before configuring a key, and a stack trace through
+		// chainClient makes an actionable one-liner look like a crash.
+		const err = new Error(
+			'No signing key. Set the MNEMONAD_KEY env var to a private key, pass --key / --phrase, ' +
+			'or pass --passkey to sign in with a passkey via the browser.'
+		);
+		err._isUserError = true;
+		throw err;
 	}
 }

package/lib/commands/buildIndex.js

@@ -0,0 +1,171 @@
+import { join } from 'node:path';
+import {
+    Indexer, TextWindowChunkingStrategy, VectorIndex, DEFAULT_DB_NAME, DEFAULT_MODEL,
+    createProvider, resolveModelName, embedderOfIndex, ModelMismatchError, MissingExtensionError,
+} from '../search/index.js';
+import { FSFolder } from '../FSFolder.js';
+import { resolvePath, DEFAULT_FS_EXCLUDES, userError } from './shared.js';
+
+/**
+ * The vector index, shared by `mnemonad index` and by `push --index` / `watch --index`.
+ * Kept in one place so all three agree on which file it is, which files it covers, and how
+ * they're chunked and embedded — an index built by `push --index` is the same index
+ * `mnemonad index` would have built.
+ *
+ * The default filename is at the folder root and not dot-prefixed: unlike `.mnemonad`, it's
+ * meant to be pushed and pulled like any other file, so a pull is searchable immediately.
+ */
+
+/** @returns {string} the index's filename (`--db`, default `search_index.db`). */
+export function indexDbName(args) {
+    return args.searchDb || DEFAULT_DB_NAME;
+}
+
+/** @returns {string[]} what the index skips: the push's own excludes, plus the index file.
+ *  The index file itself must never be walked as content to embed — explicit, not left to
+ *  chance: a SQLite file's own header/padding bytes are plausible-looking text in places,
+ *  so relying on the binary-content sniff alone to skip it would be fragile. */
+export function indexExcludes(args) {
+    const excludes = [...DEFAULT_FS_EXCLUDES, indexDbName(args)];
+    if (args.exclude) excludes.push(...args.exclude.split(',').map((s) => s.trim()));
+    return excludes;
+}
+
+function chunkingFrom(args) {
+    return new TextWindowChunkingStrategy({
+        size: args.chunkSize ?? 1000,
+        overlap: args.chunkOverlap ?? 150,
+    });
+}
+
+/**
+ * Which model to index `destPath` with. An explicit `--model` wins (an alias like `minilm`, or
+ * a full id). Without one, an existing index keeps the model it was built with — so re-indexing
+ * a folder someone indexed with MiniLM just works — and only a new index (or `--rebuild`)
+ * gets the built-in default.
+ *
+ * @returns {{model: string, embedder: ?string, dtype: ?string}}
+ */
+export function chooseModel(destPath, args) {
+    if (args.model) return { model: resolveModelName(args.model), embedder: null, dtype: null };
+    const meta = args.rebuild ? null : VectorIndex.readMeta(join(destPath, indexDbName(args)));
+    if (meta?.model) {
+        return { model: meta.model, embedder: embedderOfIndex(meta), dtype: meta.dtype || null };
+    }
+    return { model: DEFAULT_MODEL, embedder: null, dtype: null };
+}
+
+/**
+ * An Indexer configured from the CLI flags. Hold on to it across runs (as `watch --index`
+ * does) and the embedding model loads once, on first use, instead of on every run.
+ * Rejects straight away on bad chunking flags or a missing extension, before anything is
+ * read or written.
+ */
+export async function makeIndexer(destPath, args) {
+    const chunkingStrategy = chunkingFrom(args);
+    const { model, embedder, dtype } = chooseModel(destPath, args);
+    let embeddingProvider;
+    try {
+        embeddingProvider = await createProvider({ model, ...(embedder ? { embedder } : {}), dtype });
+    } catch (err) {
+        throw explainIndexError(err, destPath, args);
+    }
+    return new Indexer({ embeddingProvider, chunkingStrategy });
+}
+
+/**
+ * Builds or updates `destPath`'s index, printing the same summary `mnemonad index` does.
+ *
+ * @param {string} destPath - resolved folder path
+ * @param {Object} args - parsed CLI args (`rebuild` starts the index over)
+ * @param {Object} [opts]
+ * @param {Indexer} [opts.indexer] - reuse one (and its loaded model) across calls
+ * @param {boolean} [opts.quiet] - one summary line instead of the full report
+ * @param {boolean} [opts.rebuild] - overrides `args.rebuild` (watch rebuilds only once)
+ * @returns {Promise<{filesChanged: number, filesSkipped: number, filesRemoved: number, chunksAdded: number}>}
+ */
+export async function updateIndex(destPath, args, { indexer = null, quiet = false, rebuild = args.rebuild } = {}) {
+    indexer = indexer || await makeIndexer(destPath, { ...args, rebuild });
+    const dbName = indexDbName(args);
+    const fsFolder = new FSFolder(destPath, indexExcludes(args));
+
+    if (!quiet) {
+        console.log('  embedding model:', indexer.embeddingProvider.modelId, '(downloads and caches on first use)');
+        if (rebuild) console.log(`  rebuilding ${dbName} from scratch`);
+        console.log('  scanning for changed files...');
+    }
+    let result;
+    try {
+        result = await indexer.index(fsFolder, join(destPath, dbName), { rebuild: !!rebuild });
+    } catch (err) {
+        throw explainIndexError(err, destPath, args);
+    }
+
+    if (quiet) {
+        const changed = result.filesChanged + result.filesRemoved;
+        console.log(changed
+            ? `  index: ${result.filesChanged} file(s) re-embedded, ${result.filesRemoved} removed (${result.chunksAdded} chunks)`
+            : '  index: up to date');
+    } else {
+        console.log('  files changed:', result.filesChanged);
+        console.log('  files skipped:', result.filesSkipped, '(content unchanged since last index)');
+        console.log('  files removed:', result.filesRemoved);
+        console.log('  chunks added: ', result.chunksAdded);
+    }
+    return result;
+}
+
+/**
+ * How far `destPath`'s index has drifted from its files, without updating it — no model is
+ * loaded (not even the extension looked up) and the index is opened read-only (see
+ * Indexer.status()). Null when there's no index.
+ *
+ * @returns {Promise<?{changed: string[], added: string[], removed: string[], total: number}>}
+ */
+export async function checkIndex(destPath, args) {
+    const fsFolder = new FSFolder(destPath, indexExcludes(args));
+    // Chunking decides which files count (an empty one is never indexed), so it's configured
+    // exactly as for a real run; status() never embeds, so no provider is needed.
+    const indexer = new Indexer({ embeddingProvider: null, chunkingStrategy: chunkingFrom(args) });
+    const status = await indexer.status(fsFolder, join(destPath, indexDbName(args)));
+    if (!status) return null;
+    return { ...status, total: status.changed.length + status.added.length + status.removed.length };
+}
+
+/** Turns the two errors a user can act on into CLI messages that say what to do. */
+function explainIndexError(err, destPath, args) {
+    if (err instanceof MissingExtensionError) {
+        const lines = [err.message];
+        if (!args.model) {
+            lines.push(
+                '  Or rebuild the index with the built-in model instead:',
+                `    mnemonad index ${destPath} --rebuild`,
+            );
+        }
+        return userError(lines.join('\n'));
+    }
+    if (err instanceof ModelMismatchError) {
+        return userError(
+            `${indexDbName(args)} was built with ${err.indexModel}, but this run asked for ${err.providerModel} —\n` +
+            '  one index can\'t mix two models. Either drop --model to keep using the index\'s own model, or\n' +
+            `  add --rebuild to re-embed every file with ${err.providerModel} (the next push then uploads the\n` +
+            '  whole index again).'
+        );
+    }
+    return err;
+}
+
+/** `mnemonad index <path>` */
+export async function buildIndex(args) {
+    const destPath = resolvePath(args.path, { mustExist: true });
+    const result = await updateIndex(destPath, args);
+
+    if (result.filesChanged > 0 || result.filesRemoved > 0) {
+        // Said explicitly rather than left implicit: unlike `.mnemonad`, this file is not
+        // dot-prefixed, so the very next `push` from this folder includes it automatically —
+        // worth knowing before that push happens, not after.
+        console.log(`\n  note: ${indexDbName(args)} will be included in the next \`mnemonad push\` from this folder`);
+    } else {
+        console.log('\n  no changes — nothing new to push');
+    }
+}

package/lib/commands/burn.js

@@ -0,0 +1,59 @@
+import Mnemonad from 'mnemonad';
+import { makeChainClient, requireWalletClient } from '../chainClient.js';
+import { assertStreamOwner, formatStreamId, formatBytes } from './shared.js';
+
+/**
+ * Destroys a stream permanently: burns the ERC-721 token and clears its metadata and
+ * wrapped encryption key (`contracts/src/Mnemonad.sol`'s own `burn()`). Irreversible, and
+ * re-creating a stream with the same id afterward does NOT resurrect the old data — ids are
+ * deterministic, so the contract deliberately marks a burned id as permanently used rather
+ * than letting a fresh `create()` silently inherit old item records.
+ *
+ * Deployed CODE-tier item bytes physically survive on-chain regardless of burn — this
+ * removes the stream as a usable, readable thing, not necessarily every trace of its bytes.
+ *
+ * Requires `--yes`: the one command here that destroys something with no way back, so it
+ * refuses to run without an explicit, unambiguous opt-in rather than an interactive prompt
+ * a script could accidentally click through.
+ */
+export async function burn(args) {
+    if (!args.streamId) {
+        throw new Error('stream-id is required for burn');
+    }
+
+    const client = await makeChainClient(args);
+    requireWalletClient(client);
+
+    const mn = new Mnemonad({
+        publicClient: client.publicClient,
+        walletClient: client.walletClient,
+        contractAddress: client.contractAddress,
+        id: args.streamId,
+    });
+
+    // Ownership checked before printing anything about the stream's contents — same
+    // reasoning as every other write command's own assertStreamOwner call.
+    await assertStreamOwner(mn, client.account.address);
+    await mn.initialize();
+
+    console.log('stream:      ', formatStreamId(mn.id));
+    console.log('chain:       ', args.chain);
+    console.log('versions:    ', mn.length);
+    console.log('binary size: ', formatBytes(mn.binaryLength));
+
+    if (!args.yes) {
+        const err = new Error(
+            'This permanently destroys the stream above: the ERC-721 token and its metadata\n' +
+            '  are gone, and re-creating a stream with this id afterward does NOT recover the\n' +
+            '  old data — there is no undo. (Deployed CODE-tier chunks physically survive on\n' +
+            '  chain regardless; this only removes the stream as a usable, readable thing.)\n' +
+            '  Re-run with --yes to actually burn it.'
+        );
+        err._isUserError = true;
+        throw err;
+    }
+
+    console.log('burning...');
+    await mn.burn();
+    console.log('  done —', formatStreamId(mn.id), 'is burned.');
+}

package/lib/commands/compact.js

@@ -10,6 +10,7 @@ import {
     assertStreamOwner,
     unlockStream,
     resolveOffloadParams,
+    discoverStreamId,
 } from './shared.js';
 
 /**
@@ -19,17 +20,21 @@ import {
  * to it.
  */
 export async function compact(args) {
+    const destPath = resolvePath(args.path, { mustExist: true });
+
+    // With --manifest and no id, a folder pulled/pushed before already has one recorded —
+    // no need to require it again.
+    await discoverStreamId(args, destPath);
     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);
+    const client = await makeChainClient(args);
     requireWalletClient(client);
 
     // No `password` at construction — see shared.js's unlockStream() for why.

package/lib/commands/diff.js

@@ -8,6 +8,9 @@ import {
     formatPath,
     hashLocalTree,
     unlockStream,
+    formatStreamId,
+    folderExists,
+    discoverStreamId,
 } from './shared.js';
 
 export function compareFileMaps(localFiles, remoteFiles) {
@@ -36,14 +39,24 @@ export function compareFileMaps(localFiles, remoteFiles) {
 }
 
 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.
+    //
+    // Deliberately NOT `{ mustExist: true }`, unlike push/compact/watch: diffing a stream
+    // against a folder you haven't pulled yet is a legitimate question ("what would I get?"),
+    // and this command writes nothing either way. It is called out explicitly below though —
+    // "everything deleted" for a folder that never existed reads as data loss rather than as
+    // a wrong path.
     const destPath = resolvePath(args.path);
 
-    const client = makeChainClient(args);
+    // With --manifest and no id, a folder pulled/pushed before already has one recorded —
+    // no need to require it again.
+    await discoverStreamId(args, destPath);
+    if (!args.streamId) {
+        throw new Error('stream-id is required for diff');
+    }
+
+    const client = await makeChainClient(args);
 
     const mn = new Mnemonad({
         publicClient: client.publicClient,
@@ -61,7 +74,7 @@ export async function diff(args) {
     const totalVersions = mn.length;
 
     if (totalVersions === 0) {
-        console.log('stream', args.streamId, 'has no versions yet — nothing to diff');
+        console.log('stream', formatStreamId(args.streamId), 'has no versions yet — nothing to diff');
         return;
     }
 
@@ -70,7 +83,13 @@ export async function diff(args) {
         throw new Error('version must be between 1 and ' + totalVersions);
     }
 
-    console.log('diff:', formatPath(destPath), 'vs', args.streamId, '(version ' + version + ' of ' + totalVersions + ')');
+    console.log('diff:', formatPath(destPath), 'vs', formatStreamId(args.streamId), '(version ' + version + ' of ' + totalVersions + ')');
+    // Said up front, before the file list: without it, a mistyped path produces a list of
+    // every file in the stream marked "deleted", which reads as data loss rather than as
+    // a folder that was never there.
+    if (!folderExists(destPath)) {
+        console.log('  note: local folder does not exist — everything below is listed as deleted');
+    }
     console.log('  restoring chain version...');
 
     let remoteFolder;

package/lib/commands/index.js

@@ -4,3 +4,6 @@ export { info } from './info.js';
 export { diff } from './diff.js';
 export { watch } from './watch.js';
 export { compact } from './compact.js';
+export { burn } from './burn.js';
+export { buildIndex } from './buildIndex.js';
+export { search } from './search.js';

package/lib/commands/info.js

@@ -6,14 +6,45 @@ import {
     formatBytes,
     localTreeHash,
     unlockStream,
+    formatStreamId,
+    folderExists,
+    discoverStreamId,
+    readManifest,
+    streamIdsEqual,
 } from './shared.js';
 
 export async function info(args) {
-    const client = makeChainClient(args);
+    const client = await makeChainClient(args);
 
     console.log('  chain:          ', args.chain);
     console.log('  your wallet:    ', client.account?.address || '(none)');
 
+    // Peek at .mnemonad whenever a path is given, regardless of --manifest and regardless
+    // of whether an id was given — info is read-only, so surfacing what's there costs
+    // nothing, and it's the only command where "you have a manifest but forgot the flag" or
+    // "you gave an id that doesn't match your own manifest" are worth a note rather than a
+    // silent mismatch.
+    const manifest = args.path ? await readManifest(resolvePath(args.path)) : null;
+
+    if (manifest?.streamId) {
+        if (!args.streamId) {
+            if (args.manifest) {
+                // Logs its own "using stream id from .mnemonad manifest: ..." line.
+                await discoverStreamId(args, resolvePath(args.path));
+            } else {
+                console.log(
+                    '  manifest:       ', formatStreamId(manifest.streamId),
+                    '(.mnemonad found — pass --manifest to use it without an id)'
+                );
+            }
+        } else if (!streamIdsEqual(manifest.streamId, args.streamId)) {
+            console.log(
+                '  manifest:       ', formatStreamId(manifest.streamId),
+                '(differs from the id given:', formatStreamId(args.streamId) + ')'
+            );
+        }
+    }
+
     if (!args.streamId) {
         return;
     }
@@ -33,7 +64,7 @@ export async function info(args) {
 
     const totalVersions = mn.length;
 
-    console.log('\nstream:', args.streamId);
+    console.log('\nstream:', formatStreamId(args.streamId));
 
     const owner = await mn.owner().catch(() => null) || '(unknown)';
     const isOwner = client.account && owner !== '(unknown)' && client.account.address.toLowerCase() === owner.toLowerCase();
@@ -63,7 +94,16 @@ export async function info(args) {
         console.log('  history starts: ', 'index', mn.firstAvailableIndex, '(earlier history truncated — see `compact`)');
     }
 
+    // Deliberately NOT `{ mustExist: true }` like every other command that reads a folder:
+    // `info` is a read-only report, and "you haven't pulled this anywhere yet" is a state
+    // worth describing rather than refusing over — the stream metadata above is already
+    // printed and still useful on its own.
     const destPath = resolvePath(args.path);
+    if (!folderExists(destPath)) {
+        console.log('\n  local folder:    missing (run `mnemonad pull` to fetch it)');
+        return;
+    }
+
     const localHash = await localTreeHash(destPath);
 
     if (!localHash) {

package/lib/commands/pull.js

@@ -8,17 +8,23 @@ import {
     syncMemoryFolderToDisk,
     writeManifest,
     unlockStream,
+    formatStreamId,
+    discoverStreamId,
 } 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);
+    // With --manifest and no id, a folder pulled/pushed before already has one recorded —
+    // no need to require it again.
+    await discoverStreamId(args, destPath);
+    if (!args.streamId) {
+        throw new Error('stream-id is required for pull');
+    }
+
+    const client = await makeChainClient(args);
 
     const mn = new Mnemonad({
         publicClient: client.publicClient,
@@ -35,7 +41,7 @@ export async function pull(args) {
     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)', '...');
+    console.log('restoring', formatStreamId(args.streamId), version != null ? 'at version ' + version : '(latest)', '...');
 
     let folder;
     try {
@@ -56,7 +62,8 @@ export async function pull(args) {
     if (args.manifest) {
         await mn.initialize();
         const pulledVersion = version ?? mn.length;
-        await writeManifest(destPath, { streamId: args.streamId, version: pulledVersion, files: newFiles });
+        // Canonical form stored — see push.js's own writeManifest call for why.
+        await writeManifest(destPath, { streamId: formatStreamId(args.streamId), version: pulledVersion, files: newFiles });
     }
 
     console.log(' ', stats.written, 'written,', stats.skipped, 'unchanged,',

package/lib/commands/push.js

@@ -15,12 +15,39 @@ import {
     unlockStream,
     resolveEncryptMethod,
     resolveOffloadParams,
+    formatStreamId,
+    streamIdsEqual,
+    discoverStreamId,
+    userError,
 } from './shared.js';
+import { updateIndex, checkIndex, indexDbName } from './buildIndex.js';
 
 export async function push(args) {
+    const destPath = resolvePath(args.path, { mustExist: true });
+
+    // With --manifest and no id, a folder pushed before already has one recorded — reuse it
+    // rather than falling into the "no id" branch below and creating a second, unrelated
+    // stream for the same folder.
+    await discoverStreamId(args, destPath);
     let streamId = args.streamId;
 
-    const destPath = resolvePath(args.path);
+    // Before anything is scanned or signed: the push below then picks the updated index up
+    // like any other file. A failure stops the push outright — a push that silently went out
+    // without the index asked for would leave the stream unsearchable with no sign of why.
+    if (args.rebuild && !args.index) {
+        throw userError('--rebuild only applies with --index (it starts the search index over)');
+    }
+    if (args.index) {
+        console.log(args.rebuild ? '  rebuilding search index...' : '  updating search index...');
+        try {
+            await updateIndex(destPath, args, { quiet: true });
+        } catch (err) {
+            throw userError(`indexing failed, so nothing was pushed: ${err.message}`);
+        }
+    } else {
+        await warnIfIndexStale(destPath, args);
+    }
+
     const fsFolder = new FSFolder(destPath, makeExcludes(args));
 
     const counts = await countTree(fsFolder);
@@ -29,7 +56,7 @@ export async function push(args) {
     if (args.manifest) {
         const manifest = await readManifest(destPath);
         const localFiles = await hashLocalTree(fsFolder);
-        if (streamId && manifest && manifest.streamId === streamId && manifest.files) {
+        if (streamId && manifest && streamIdsEqual(manifest.streamId, streamId) && manifest.files) {
             if (hashMapsEqual(localFiles, manifest.files)) {
                 console.log('  no changes since last pull, nothing to push');
                 return;
@@ -37,7 +64,7 @@ export async function push(args) {
         }
     }
 
-    const client = makeChainClient(args);
+    const client = await makeChainClient(args);
     requireWalletClient(client);
 
     const baseParams = {
@@ -73,7 +100,7 @@ export async function push(args) {
         console.log('creating new stream on', args.chain, how, '...');
         mn = await Mnemonad.create(createParams);
         streamId = mn.id.toString();
-        console.log('  created:', streamId);
+        console.log('  created:', formatStreamId(streamId));
     } else {
         mn = new Mnemonad({ ...baseParams, id: streamId });
         await assertStreamOwner(mn, client.account.address);
@@ -83,7 +110,7 @@ export async function push(args) {
         }
     }
 
-    console.log('syncing ./ →', streamId);
+    console.log('syncing ./ →', formatStreamId(streamId));
 
     const monadSync = new MonadSync({ mnemonad: mn, compress: args.compress || 'gzip' });
 
@@ -118,10 +145,37 @@ export async function push(args) {
     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);
+    console.log('  stream:', formatStreamId(streamId));
 
     if (args.manifest) {
         const localFiles = await hashLocalTree(fsFolder);
-        await writeManifest(destPath, { streamId, version: result.version, files: localFiles });
+        // Stored canonical (see formatStreamId) rather than whatever form the caller typed —
+        // so a manifest written by a hex-id push and read back by a decimal-id one (or vice
+        // versa) still matches; streamIdsEqual() above is the belt to this suspenders.
+        await writeManifest(destPath, { streamId: formatStreamId(streamId), version: result.version, files: localFiles });
+    }
+}
+
+/**
+ * A folder that already carries an index, pushed without `--index` after its files changed,
+ * would publish an index that no longer matches them — searches keep returning the old text's
+ * offsets. Cheap to catch (a hash per file, no model load, the index opened read-only) and
+ * worth a line; never a reason to fail the push itself.
+ */
+async function warnIfIndexStale(destPath, args) {
+    let status;
+    try {
+        status = await checkIndex(destPath, args);
+    } catch {
+        return;
     }
+    if (!status || status.total === 0) return;
+    const parts = [];
+    if (status.changed.length) parts.push(`${status.changed.length} changed`);
+    if (status.added.length) parts.push(`${status.added.length} new`);
+    if (status.removed.length) parts.push(`${status.removed.length} removed`);
+    console.log(
+        `  note: ${indexDbName(args)} is out of date (${parts.join(', ')} file(s) since it was built).\n` +
+        '        Push with --index to update it first, or run `mnemonad index <path>`.'
+    );
 }