resplite 1.2.2 → 1.2.4

package/README.md

@@ -176,11 +176,109 @@ const srv = await createRESPlite({
 
 ## Migration from Redis
 
-RESPLite is a good fit for migrating **non-replicated Redis** instances that have **grown large** (e.g. tens of GB) and where RESPLite's latency is acceptable. The SPEC_F flow (dirty-key tracker, bulk import, cutover) is designed for that scenario with minimal downtime.
+RESPLite is a good fit for migrating **non-replicated Redis** instances that have **grown large** (e.g. tens of GB) and where RESPLite's latency is acceptable. The flow (dirty-key tracker, bulk import, cutover) is designed for that scenario with minimal downtime.
 
 Migration supports two modes:
 
-### Simple one-shot import (legacy)
+### Programmatic migration API (JavaScript)
+
+As an alternative to the CLI, the full migration flow is available as a JavaScript API via `resplite/migration`. Useful for embedding the migration inside your own scripts or automation pipelines.
+
+```javascript
+import { createMigration } from 'resplite/migration';
+
+const m = createMigration({
+  from:  'redis://127.0.0.1:6379',  // source Redis URL (default)
+  to:    './resplite.db',           // destination SQLite DB path (required)
+  runId: 'my-migration-1',          // unique run ID (required for bulk/status/applyDirty)
+
+  // optional — same defaults as the CLI:
+  scanCount:      1000,
+  batchKeys:      200,
+  batchBytes:     64 * 1024 * 1024,  // 64 MB
+  maxRps:         0,                  // 0 = unlimited
+  pragmaTemplate: 'default',
+
+  // If your Redis deployment renamed CONFIG for security:
+  // configCommand: 'MYCONFIG',
+});
+
+// Step 0 — Preflight: inspect Redis before starting
+const info = await m.preflight();
+console.log('keys (estimate):', info.keyCountEstimate);
+console.log('type distribution:', info.typeDistribution);
+console.log('notify-keyspace-events:', info.notifyKeyspaceEvents);
+console.log('CONFIG available:', info.configCommandAvailable);  // false if renamed
+console.log('recommended params:', info.recommended);
+
+// Step 0b — Enable keyspace notifications (required for dirty-key tracking)
+// Reads the current value and merges the new flags — existing flags are preserved.
+const ks = await m.enableKeyspaceNotifications();
+// → { ok: true, previous: '', applied: 'KEA' }
+// If CONFIG is renamed and configCommand was not set, ok=false and error explains how to fix it.
+
+// Step 1 — Bulk import (checkpointed, resumable). Same script to start or continue.
+// Use keyCountEstimate from preflight to show progress % (estimate; actual count may change).
+const total = info.keyCountEstimate || 1;
+await m.bulk({
+  onProgress: (r) => {
+    const pct = total ? ((r.scanned_keys / total) * 100).toFixed(1) : '—';
+    console.log(
+      `scanned=${r.scanned_keys} migrated=${r.migrated_keys} errors=${r.error_keys} progress=${pct}%`
+    );
+  },
+});
+
+// Check status at any point (synchronous, no Redis needed)
+const { run, dirty } = m.status();
+console.log('bulk status:', run.status, '— dirty counts:', dirty);
+
+// Step 2 — Apply dirty keys that changed in Redis during bulk
+await m.applyDirty();
+
+// Step 3 — Verify a sample of keys match between Redis and the destination
+const result = await m.verify({ samplePct: 0.5, maxSample: 10000 });
+console.log(`verified ${result.sampled} keys — mismatches: ${result.mismatches.length}`);
+
+// Disconnect Redis when done
+await m.close();
+```
+
+**Automatic resume (default)**  
+`resume` defaults to `true`. It doesn't matter whether it's the first run or a resume: the same script works for both starting and continuing. The first run starts from cursor 0; if the process is interrupted (Ctrl+C, crash, etc.), running the script again continues from the last checkpoint. You don't need to pass `resume: false` on the first run or change anything to resume.
+
+**Graceful shutdown**  
+On SIGINT (Ctrl+C) or SIGTERM, the bulk importer checkpoints progress, sets the run status to `aborted`, closes the SQLite database cleanly (so WAL is checkpointed and the file is not left open), then exits. You can safely interrupt a long-running bulk and resume later.
+
+The dirty-key tracker (to capture writes during bulk) still runs as a separate process via `npx resplite-dirty-tracker`. The API above handles everything else in a single script.
+
+#### Renamed CONFIG command
+
+If your Redis instance has the `CONFIG` command renamed (a common hardening practice), pass the new name to `createMigration`:
+
+```javascript
+const m = createMigration({
+  from: 'redis://10.0.0.10:6379',
+  to:   './resplite.db',
+  runId: 'run_001',
+  configCommand: 'MYCONFIG',  // the renamed command
+});
+
+// preflight will use MYCONFIG GET notify-keyspace-events
+const info = await m.preflight();
+// info.configCommandAvailable → false if the name is wrong
+
+// enableKeyspaceNotifications will use MYCONFIG SET notify-keyspace-events KEA
+const result = await m.enableKeyspaceNotifications({ value: 'KEA' });
+```
+
+The same flag is available in the CLI:
+
+```bash
+npx resplite-dirty-tracker start --run-id run_001 --to ./resplite.db \
+  --from redis://10.0.0.10:6379 --config-command MYCONFIG
+```
+### Simple one-shot import
 
 For small datasets or when downtime is acceptable:
 
@@ -211,14 +309,17 @@ Examples:
 # One-shot import from authenticated Redis
 npm run import-from-redis -- --db ./migrated.db --redis-url "redis://:mysecret@127.0.0.1:6379"
 
-# SPEC_F flow: use --from with the full URL (or set RESPLITE_IMPORT_FROM)
+# flow: use --from with the full URL (or set RESPLITE_IMPORT_FROM)
 npx resplite-import preflight --from "redis://:mysecret@10.0.0.10:6379" --to ./resplite.db
 npx resplite-dirty-tracker start --run-id run_001 --from "redis://:mysecret@10.0.0.10:6379" --to ./resplite.db
 ```
 
 For one-shot import, authentication is only available when using `--redis-url`; the `--host` / `--port` options do not support a password.
 
-### Minimal-downtime migration (SPEC_F)
+**Search indices (FT.\*)**  
+The KV bulk migration imports only the Redis keyspace (strings, hashes, sets, lists, zsets). RediSearch index schemas and documents are migrated separately with the `migrate-search` step — see [Migrating RediSearch indices](#migrating-redisearch-indices) below.
+
+### Minimal-downtime migration
 
 For large datasets (~30 GB), use the Dirty Key Registry flow so the bulk of the migration runs online and only a short cutover is needed.
 
@@ -278,97 +379,6 @@ notify-keyspace-events KEA
 
 Then start RespLite with the migrated DB: `RESPLITE_DB=./resplite.db npm start`.
 
-### Programmatic migration API (JavaScript)
-
-As an alternative to the CLI, the full migration flow is available as a JavaScript API via `resplite/migration`. Useful for embedding the migration inside your own scripts or automation pipelines.
-
-```javascript
-import { createMigration } from 'resplite/migration';
-
-const m = createMigration({
-  from:  'redis://127.0.0.1:6379',  // source Redis URL (default)
-  to:    './resplite.db',           // destination SQLite DB path (required)
-  runId: 'my-migration-1',          // unique run ID (required for bulk/status/applyDirty)
-
-  // optional — same defaults as the CLI:
-  scanCount:      1000,
-  batchKeys:      200,
-  batchBytes:     64 * 1024 * 1024,  // 64 MB
-  maxRps:         0,                  // 0 = unlimited
-  pragmaTemplate: 'default',
-
-  // If your Redis deployment renamed CONFIG for security:
-  // configCommand: 'MYCONFIG',
-});
-
-// Step 0 — Preflight: inspect Redis before starting
-const info = await m.preflight();
-console.log('keys (estimate):', info.keyCountEstimate);
-console.log('type distribution:', info.typeDistribution);
-console.log('notify-keyspace-events:', info.notifyKeyspaceEvents);
-console.log('CONFIG available:', info.configCommandAvailable);  // false if renamed
-console.log('recommended params:', info.recommended);
-
-// Step 0b — Enable keyspace notifications (required for dirty-key tracking)
-// Reads the current value and merges the new flags — existing flags are preserved.
-const ks = await m.enableKeyspaceNotifications();
-// → { ok: true, previous: '', applied: 'KEA' }
-// If CONFIG is renamed and configCommand was not set, ok=false and error explains how to fix it.
-
-// Step 1 — Bulk import (checkpointed, resumable). Same script to start or continue.
-await m.bulk({
-  onProgress: (r) => console.log(
-    `scanned=${r.scanned_keys} migrated=${r.migrated_keys} errors=${r.error_keys}`
-  ),
-});
-
-// Check status at any point (synchronous, no Redis needed)
-const { run, dirty } = m.status();
-console.log('bulk status:', run.status, '— dirty counts:', dirty);
-
-// Step 2 — Apply dirty keys that changed in Redis during bulk
-await m.applyDirty();
-
-// Step 3 — Verify a sample of keys match between Redis and the destination
-const result = await m.verify({ samplePct: 0.5, maxSample: 10000 });
-console.log(`verified ${result.sampled} keys — mismatches: ${result.mismatches.length}`);
-
-// Disconnect Redis when done
-await m.close();
-```
-
-**Resume automático (por defecto)**  
-`resume` viene en `true` por defecto. Da igual si es la primera vez o una reanudación: el mismo script sirve para empezar y para continuar. La primera ejecución arranca desde cursor 0; si el proceso se corta (Ctrl+C, crash, etc.), al volver a ejecutar el script continúa desde el último checkpoint. No hace falta pasar `resume: false` la primera vez ni cambiar nada para reanudar.
-
-The dirty-key tracker (to capture writes during bulk) still runs as a separate process via `npx resplite-dirty-tracker`. The API above handles everything else in a single script.
-
-#### Renamed CONFIG command
-
-If your Redis instance has the `CONFIG` command renamed (a common hardening practice), pass the new name to `createMigration`:
-
-```javascript
-const m = createMigration({
-  from: 'redis://10.0.0.10:6379',
-  to:   './resplite.db',
-  runId: 'run_001',
-  configCommand: 'MYCONFIG',  // the renamed command
-});
-
-// preflight will use MYCONFIG GET notify-keyspace-events
-const info = await m.preflight();
-// info.configCommandAvailable → false if the name is wrong
-
-// enableKeyspaceNotifications will use MYCONFIG SET notify-keyspace-events KEA
-const result = await m.enableKeyspaceNotifications({ value: 'KEA' });
-```
-
-The same flag is available in the CLI:
-
-```bash
-npx resplite-dirty-tracker start --run-id run_001 --to ./resplite.db \
-  --from redis://10.0.0.10:6379 --config-command MYCONFIG
-```
-
 #### Low-level re-exports
 
 If you need more control, the individual functions and registry helpers are also exported:
@@ -551,9 +561,66 @@ await c2.quit();
 await srv2.close();
 ```
 
-## Compatibility matrix
+### Migrating RediSearch indices
+
+If your Redis source uses **RediSearch** (Redis Stack or the `redis/search` module), run `migrate-search` after (or during) the KV bulk import. It reads index schemas with `FT.INFO`, creates them in RespLite, and imports documents by scanning the matching hash keys.
 
-RESPLite implements **47 core Redis commands** (~19% of the ~246 commands in Redis 7). The uncovered 81% is mostly entire subsystems that are out of scope by design: pub/sub (~10 commands), Streams (~20), cluster/replication (~30), Lua scripting (~5), server admin (~40), and extended variants of data-structure commands. For typical single-node application workloads — strings, hashes, sets, lists, sorted sets, key TTLs — coverage is close to the commands developers reach for daily.
+**CLI:**
+
+```bash
+# Migrate all indices
+npx resplite-import migrate-search \
+  --from redis://10.0.0.10:6379 \
+  --to   ./resplite.db
+
+# Migrate specific indices only
+npx resplite-import migrate-search \
+  --from redis://10.0.0.10:6379 \
+  --to   ./resplite.db \
+  --index products \
+  --index articles
+
+# Options
+#   --scan-count N          SCAN COUNT hint (default 500)
+#   --max-rps N             throttle Redis reads
+#   --batch-docs N          docs per SQLite transaction (default 200)
+#   --max-suggestions N     cap for suggestion import (default 10000)
+#   --no-skip               overwrite if the index already exists in RespLite
+#   --no-suggestions        skip suggestion import
+```
+
+**Programmatic API:**
+
+```javascript
+const m = createMigration({ from, to, runId });
+
+const result = await m.migrateSearch({
+  onlyIndices:     ['products', 'articles'], // omit to migrate all
+  batchDocs:       200,
+  maxSuggestions:  10000,
+  skipExisting:    true,   // default
+  withSuggestions: true,   // default
+  onProgress: (r) => console.log(r.name, r.docsImported, r.warnings),
+});
+// result.indices: [{ name, created, skipped, docsImported, docsSkipped, docErrors, sugsImported, warnings, error? }]
+// result.aborted: true if interrupted by SIGINT/SIGTERM
+```
+
+**What gets migrated:**
+
+| RediSearch type | RespLite | Notes |
+|---|---|---|
+| TEXT | TEXT | Direct |
+| TAG | TEXT | Values preserved; TAG filtering lost |
+| NUMERIC | TEXT | Stored as string; numeric range queries not supported |
+| GEO, VECTOR, … | skipped | Warning emitted per field |
+
+- Only **HASH**-based indices are supported. JSON (RedisJSON) indices are skipped.
+- A `payload` field is added automatically if none of the source fields maps to it.
+- Suggestions are imported via `FT.SUGGET "" MAX n WITHSCORES` (no cursor; capped at `maxSuggestions`).
+- Graceful shutdown: Ctrl+C finishes the current document, closes SQLite cleanly, and exits with a non-zero code.
+
+## Compatibility matrix
 
 ### Supported (v1)
 
@@ -594,7 +661,7 @@ Unsupported commands return: `ERR command not supported yet`.
 | `npm run test:stress` | Stress tests |
 | `npm run benchmark` | Comparative benchmark Redis vs RESPLite |
 | `npm run import-from-redis` | One-shot import from Redis into a SQLite DB |
-| `npx resplite-import` (preflight, bulk, status, apply-dirty, verify) | Migration CLI (SPEC_F minimal-downtime flow) |
+| `npx resplite-import` (preflight, bulk, status, apply-dirty, verify) | Migration CLI (minimal-downtime flow) |
 | `npx resplite-dirty-tracker <start\|stop>` | Dirty-key tracker for migration cutover |
 
 ## Specification

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "resplite",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "A RESP2 server with practical Redis compatibility, backed by SQLite",
   "type": "module",
   "main": "src/index.js",

package/spec/SPEC_F.md

@@ -13,6 +13,7 @@
 * Perfect change-data-capture guarantees equivalent to replication logs.
 * Distributed migration across multiple import workers with strict ordering semantics.
 * Full fidelity for unsupported Redis data types (streams, modules, Lua scripts, etc.).
+* **Search indices (FT.\*):** Keyspace migration (`bulk` / `apply-dirty`) copies only the Redis KV data (strings, hashes, sets, lists, zsets). RediSearch index schemas and documents are migrated separately via the `migrate-search` step (§F.10).
 
 ---
 
@@ -258,6 +259,18 @@ Persist:
 
 If interrupted, `--resume` restarts from the stored cursor.
 
+## F.7.2.1 Graceful shutdown (SIGINT / SIGTERM)
+
+When the bulk import process receives SIGINT or SIGTERM it must:
+
+* Stop the import loop after the current key (no partial key).
+* Write a final checkpoint (cursor and counters) so progress is persisted.
+* Set run status to `aborted`.
+* Close the SQLite database handle so WAL is checkpointed and the file is not left open.
+* Remove signal handlers and exit (rethrow so the process exits non-zero).
+
+This ensures the destination DB is always closed cleanly when the process is killed or interrupted; the next run with `--resume` continues from the last checkpoint.
+
 ## F.7.3 Throughput controls
 
 The importer must support:
@@ -497,6 +510,87 @@ If dirty tracker disconnects:
 
 ---
 
+# F.10 Search Index Migration (FT.* / RediSearch)
+
+## F.10.1 Overview
+
+When the source is a Redis instance with **RediSearch** (Redis Stack or the `redis/search` module), search indices can be migrated with the `migrate-search` step. This step is independent of the KV bulk import and can be run at any time (before or after `bulk`).
+
+## F.10.2 Algorithm
+
+For each index in the source:
+
+1. **`FT._LIST`** → enumerate all index names.
+2. **`FT.INFO <name>`** → read `index_definition` (key type, prefix patterns) and `attributes` (field names and types).
+3. **Schema mapping** (see §F.10.3).
+4. **`FT.CREATE`** in RespLite with the mapped schema. Skip if already exists (controlled by `skipExisting`).
+5. **SCAN** keys matching each index prefix → **HGETALL** → `addDocument` in SQLite batches.
+6. **`FT.SUGGET "" MAX n WITHSCORES`** → import suggestions into RespLite.
+
+## F.10.3 Field type mapping
+
+| RediSearch type | RespLite type | Notes |
+|-----------------|---------------|-------|
+| TEXT            | TEXT          | Direct mapping |
+| TAG             | TEXT          | Values preserved as-is; TAG filtering semantics lost |
+| NUMERIC         | TEXT          | Values stored as strings; numeric range queries not supported |
+| GEO, VECTOR, … | —             | Skipped with warning |
+
+RespLite requires a `payload` TEXT field. If none of the source fields maps to `payload`, a `payload` field is added automatically and synthesised at import time by concatenating all other text values.
+
+## F.10.4 Constraints
+
+* Only **HASH**-based indices are supported (`key_type = HASH`). JSON indices (RedisJSON) are skipped with an error.
+* Index names must match `[A-Za-z][A-Za-z0-9:_-]{0,63}`. Indices with invalid names are skipped with an error.
+* `FT.SUGGET` has no cursor; suggestions are imported up to `maxSuggestions` (default 10 000).
+* Document score is read from the `__score` or `score` hash field if present; defaults to `1.0`.
+
+## F.10.5 Graceful shutdown
+
+Same pattern as `bulk` (§F.7.2.1): SIGINT/SIGTERM finishes the current document, closes the SQLite DB cleanly, and exits with a non-zero code.
+
+## F.10.6 CLI
+
+```bash
+# Migrate all RediSearch indices
+resplite-import migrate-search \
+  --from redis://10.0.0.10:6379 \
+  --to   ./resplite.db
+
+# Migrate specific indices only
+resplite-import migrate-search \
+  --from redis://10.0.0.10:6379 \
+  --to   ./resplite.db \
+  --index products \
+  --index articles
+
+# Options
+#   --scan-count N          SCAN COUNT hint (default 500)
+#   --max-rps N             throttle (default unlimited)
+#   --batch-docs N          docs per SQLite transaction (default 200)
+#   --max-suggestions N     cap for FT.SUGGET (default 10000)
+#   --no-skip               overwrite if index already exists
+#   --no-suggestions        skip suggestion import
+```
+
+## F.10.7 Programmatic API
+
+```javascript
+const m = createMigration({ from, to, runId });
+
+const result = await m.migrateSearch({
+  onlyIndices:    ['products', 'articles'], // omit for all
+  batchDocs:      200,
+  maxSuggestions: 10000,
+  skipExisting:   true,
+  withSuggestions: true,
+  onProgress: (r) => console.log(r.name, r.docsImported, r.warnings),
+});
+// result: { indices: [{ name, created, skipped, docsImported, docsSkipped, docErrors, sugsImported, warnings, error? }], aborted }
+```
+
+---
+
 # F.12 Operational Guidance (Large datasets)
 
 * Use a dedicated Redis replica for reads if possible to reduce load on primary.

package/src/cli/resplite-import.js

@@ -11,9 +11,10 @@ import { runPreflight } from '../migration/preflight.js';
 import { runBulkImport } from '../migration/bulk.js';
 import { runApplyDirty } from '../migration/apply-dirty.js';
 import { runVerify } from '../migration/verify.js';
+import { runMigrateSearch } from '../migration/migrate-search.js';
 import { getRun, getDirtyCounts } from '../migration/registry.js';
 
-const SUBCOMMANDS = ['preflight', 'bulk', 'status', 'apply-dirty', 'verify'];
+const SUBCOMMANDS = ['preflight', 'bulk', 'status', 'apply-dirty', 'verify', 'migrate-search'];
 
 function parseArgs(argv = process.argv.slice(2)) {
   const args = { _: [] };
@@ -53,6 +54,17 @@ function parseArgs(argv = process.argv.slice(2)) {
       args.pragmaTemplate = argv[++i];
     } else if (arg === '--sample' && argv[i + 1]) {
       args.sample = argv[++i];
+    } else if (arg === '--index' && argv[i + 1]) {
+      if (!args.index) args.index = [];
+      args.index.push(argv[++i]);
+    } else if (arg === '--batch-docs' && argv[i + 1]) {
+      args.batchDocs = parseInt(argv[++i], 10);
+    } else if (arg === '--max-suggestions' && argv[i + 1]) {
+      args.maxSuggestions = parseInt(argv[++i], 10);
+    } else if (arg === '--no-skip') {
+      args.noSkip = true;
+    } else if (arg === '--no-suggestions') {
+      args.noSuggestions = true;
     } else if (arg.startsWith('--')) {
       args[arg.slice(2).replace(/-/g, '')] = argv[i + 1] ?? true;
       if (argv[i + 1] && !argv[i + 1].startsWith('--')) i++;
@@ -200,28 +212,73 @@ async function cmdVerify(args) {
   }
 }
 
+async function cmdMigrateSearch(args) {
+  const redisUrl = getRedisUrl(args);
+  const dbPath   = getDbPath(args);
+  const client   = createClient({ url: redisUrl });
+  client.on('error', (e) => console.error('Redis:', e.message));
+  await client.connect();
+  try {
+    const onlyIndices = args.index
+      ? (Array.isArray(args.index) ? args.index : [args.index])
+      : null;
+
+    const result = await runMigrateSearch(client, dbPath, {
+      pragmaTemplate:  args.pragmaTemplate || 'default',
+      onlyIndices,
+      scanCount:       args.scanCount       || 500,
+      maxRps:          args.maxRps          || 0,
+      batchDocs:       args.batchDocs       || 200,
+      maxSuggestions:  args.maxSuggestions  || 10000,
+      skipExisting:    args.noSkip ? false : true,
+      withSuggestions: args.noSuggestions ? false : true,
+      onProgress: (r) => {
+        const status = r.error ? `ERROR: ${r.error}` : (r.skipped ? 'skipped (already exists)' : 'created');
+        console.log(`  [${r.name}] ${status} — docs=${r.docsImported} skipped=${r.docsSkipped} errors=${r.docErrors} sugs=${r.sugsImported}`);
+        if (r.warnings?.length) r.warnings.forEach((w) => console.log(`    WARN: ${w}`));
+      },
+    });
+
+    if (result.aborted) console.log('Migration aborted by signal.');
+    console.log(`Done. Indices processed: ${result.indices.length}`);
+    const errors = result.indices.filter((i) => i.error);
+    if (errors.length) {
+      console.error(`  ${errors.length} index(es) failed:`);
+      errors.forEach((i) => console.error(`  - ${i.name}: ${i.error}`));
+    }
+  } finally {
+    await client.quit();
+  }
+}
+
 async function main() {
   const args = parseArgs();
   const sub = args._[0];
   if (!SUBCOMMANDS.includes(sub)) {
-    console.error('Usage: resplite-import <preflight|bulk|status|apply-dirty|verify> [options]');
-    console.error('  --from <redis-url>   (default: redis://127.0.0.1:6379)');
-    console.error('  --to <db-path>       (required for bulk, status, apply-dirty, verify)');
-    console.error('  --run-id <id>        (required for bulk, status, apply-dirty)');
-    console.error('  --scan-count N       (bulk, default 1000)');
-    console.error('  --max-rps N          (bulk, apply-dirty)');
-    console.error('  --batch-keys N       (default 200)');
-    console.error('  --batch-bytes N[MB|KB|GB] (default 64MB)');
-    console.error('  --resume / --no-resume  (bulk: default resume=on; use --no-resume to always start from 0)');
-    console.error('  --sample 0.5%        (verify, default 0.5%)');
+    console.error('Usage: resplite-import <preflight|bulk|status|apply-dirty|verify|migrate-search> [options]');
+    console.error('  --from <redis-url>       (default: redis://127.0.0.1:6379)');
+    console.error('  --to <db-path>           (required for bulk, status, apply-dirty, verify, migrate-search)');
+    console.error('  --run-id <id>            (required for bulk, status, apply-dirty)');
+    console.error('  --scan-count N           (bulk / migrate-search, default 1000 / 500)');
+    console.error('  --max-rps N              (bulk, apply-dirty, migrate-search)');
+    console.error('  --batch-keys N           (default 200)');
+    console.error('  --batch-bytes N[MB|KB|GB](default 64MB)');
+    console.error('  --resume / --no-resume   (bulk: default resume=on)');
+    console.error('  --sample 0.5%            (verify, default 0.5%)');
+    console.error('  --index <name>           (migrate-search: repeat for multiple; omit for all indices)');
+    console.error('  --batch-docs N           (migrate-search: docs per SQLite tx, default 200)');
+    console.error('  --max-suggestions N      (migrate-search: cap for FT.SUGGET, default 10000)');
+    console.error('  --no-skip                (migrate-search: overwrite if index exists)');
+    console.error('  --no-suggestions         (migrate-search: skip suggestion import)');
     process.exit(1);
   }
   try {
-    if (sub === 'preflight') await cmdPreflight(args);
-    else if (sub === 'bulk') await cmdBulk(args);
-    else if (sub === 'status') await cmdStatus(args);
-    else if (sub === 'apply-dirty') await cmdApplyDirty(args);
-    else if (sub === 'verify') await cmdVerify(args);
+    if (sub === 'preflight')       await cmdPreflight(args);
+    else if (sub === 'bulk')       await cmdBulk(args);
+    else if (sub === 'status')     await cmdStatus(args);
+    else if (sub === 'apply-dirty')await cmdApplyDirty(args);
+    else if (sub === 'verify')     await cmdVerify(args);
+    else if (sub === 'migrate-search') await cmdMigrateSearch(args);
   } catch (err) {
     console.error(err);
     process.exit(1);
@@ -236,4 +293,4 @@ if (isMain) {
   });
 }
 
-export { parseArgs, cmdPreflight, cmdBulk, cmdStatus, cmdApplyDirty, cmdVerify };
+export { parseArgs, cmdPreflight, cmdBulk, cmdStatus, cmdApplyDirty, cmdVerify, cmdMigrateSearch };