layercache 2.0.0 → 3.0.0

package/dist/cli.cjs

@@ -216,20 +216,30 @@ var PatternMatcher = class _PatternMatcher {
 };
 
 // src/invalidation/RedisTagIndex.ts
+var DEFAULT_KNOWN_KEYS_SHARDS = 16;
 var RedisTagIndex = class {
   client;
   prefix;
   scanCount;
   knownKeysShards;
+  logger;
+  warnedLegacyKnownKeys = false;
   constructor(options) {
     this.client = options.client;
     this.prefix = options.prefix ?? "layercache:tag-index";
     this.scanCount = options.scanCount ?? 100;
     this.knownKeysShards = normalizeKnownKeysShards(options.knownKeysShards);
+    this.logger = options.logger;
   }
+  /**
+   * Records a key as known without changing tag assignments.
+   */
   async touch(key) {
     await this.client.sadd(this.knownKeysKeyFor(key), key);
   }
+  /**
+   * Replaces the tags associated with a key and records the key as known.
+   */
   async track(key, tags) {
     const keyTagsKey = this.keyTagsKey(key);
     const existingTags = await this.client.smembers(keyTagsKey);
@@ -247,20 +257,32 @@ var RedisTagIndex = class {
     }
     await pipeline.exec();
   }
+  /**
+   * Removes a key from all tag mappings and known-key tracking.
+   */
   async remove(key) {
     const keyTagsKey = this.keyTagsKey(key);
     const existingTags = await this.client.smembers(keyTagsKey);
     const pipeline = this.client.pipeline();
     pipeline.srem(this.knownKeysKeyFor(key), key);
+    if (this.knownKeysShards > 1) {
+      pipeline.srem(this.legacyKnownKeysKey(), key);
+    }
     pipeline.del(keyTagsKey);
     for (const tag of existingTags) {
       pipeline.srem(this.tagKeysKey(tag), key);
     }
     await pipeline.exec();
   }
+  /**
+   * Returns keys currently associated with a tag.
+   */
   async keysForTag(tag) {
     return this.client.smembers(this.tagKeysKey(tag));
   }
+  /**
+   * Visits keys currently associated with a tag.
+   */
   async forEachKeyForTag(tag, visitor) {
     let cursor = "0";
     const tagKey = this.tagKeysKey(tag);
@@ -272,38 +294,56 @@ var RedisTagIndex = class {
       }
     } while (cursor !== "0");
   }
+  /**
+   * Returns known keys that start with a prefix.
+   */
   async keysForPrefix(prefix) {
-    const matches = [];
-    for (const knownKeysKey of this.knownKeysKeys()) {
+    const matches = /* @__PURE__ */ new Set();
+    for (const knownKeysKey of await this.knownKeysKeysForRead()) {
       let cursor = "0";
       do {
         const [nextCursor, keys] = await this.client.sscan(knownKeysKey, cursor, "COUNT", this.scanCount);
         cursor = nextCursor;
-        matches.push(...keys.filter((key) => key.startsWith(prefix)));
+        for (const key of keys) {
+          if (key.startsWith(prefix)) {
+            matches.add(key);
+          }
+        }
       } while (cursor !== "0");
     }
-    return matches;
+    return [...matches];
   }
+  /**
+   * Visits known keys that start with a prefix.
+   */
   async forEachKeyForPrefix(prefix, visitor) {
-    for (const knownKeysKey of this.knownKeysKeys()) {
+    const visited = /* @__PURE__ */ new Set();
+    for (const knownKeysKey of await this.knownKeysKeysForRead()) {
       let cursor = "0";
       do {
         const [nextCursor, keys] = await this.client.sscan(knownKeysKey, cursor, "COUNT", this.scanCount);
         cursor = nextCursor;
         for (const key of keys) {
-          if (key.startsWith(prefix)) {
+          if (key.startsWith(prefix) && !visited.has(key)) {
+            visited.add(key);
             await visitor(key);
           }
         }
       } while (cursor !== "0");
     }
   }
+  /**
+   * Returns the tags currently associated with a key.
+   */
   async tagsForKey(key) {
     return this.client.smembers(this.keyTagsKey(key));
   }
+  /**
+   * Returns known keys matching a wildcard pattern.
+   */
   async matchPattern(pattern) {
-    const matches = [];
-    for (const knownKeysKey of this.knownKeysKeys()) {
+    const matches = /* @__PURE__ */ new Set();
+    for (const knownKeysKey of await this.knownKeysKeysForRead()) {
       let cursor = "0";
       do {
         const [nextCursor, keys] = await this.client.sscan(
@@ -315,13 +355,21 @@ var RedisTagIndex = class {
           this.scanCount
         );
         cursor = nextCursor;
-        matches.push(...keys.filter((key) => PatternMatcher.matches(pattern, key)));
+        for (const key of keys) {
+          if (PatternMatcher.matches(pattern, key)) {
+            matches.add(key);
+          }
+        }
       } while (cursor !== "0");
     }
-    return matches;
+    return [...matches];
   }
+  /**
+   * Visits known keys matching a wildcard pattern.
+   */
   async forEachKeyMatchingPattern(pattern, visitor) {
-    for (const knownKeysKey of this.knownKeysKeys()) {
+    const visited = /* @__PURE__ */ new Set();
+    for (const knownKeysKey of await this.knownKeysKeysForRead()) {
       let cursor = "0";
       do {
         const [nextCursor, keys] = await this.client.sscan(
@@ -334,13 +382,17 @@ var RedisTagIndex = class {
         );
         cursor = nextCursor;
         for (const key of keys) {
-          if (PatternMatcher.matches(pattern, key)) {
+          if (PatternMatcher.matches(pattern, key) && !visited.has(key)) {
+            visited.add(key);
             await visitor(key);
           }
         }
       } while (cursor !== "0");
     }
   }
+  /**
+   * Clears all Redis tag-index state under this prefix.
+   */
   async clear() {
     const indexKeys = await this.scanIndexKeys();
     if (indexKeys.length === 0) {
@@ -348,6 +400,31 @@ var RedisTagIndex = class {
     }
     await this.client.del(...indexKeys);
   }
+  async migrateLegacyKnownKeys() {
+    if (this.knownKeysShards === 1) {
+      return { migratedKeys: 0 };
+    }
+    const legacyKey = this.legacyKnownKeysKey();
+    let cursor = "0";
+    let migratedKeys = 0;
+    do {
+      const [nextCursor, keys] = await this.client.sscan(legacyKey, cursor, "COUNT", this.scanCount);
+      cursor = nextCursor;
+      if (keys.length === 0) {
+        continue;
+      }
+      const pipeline = this.client.pipeline();
+      for (const key of keys) {
+        pipeline.sadd(this.knownKeysKeyFor(key), key);
+      }
+      await pipeline.exec();
+      migratedKeys += keys.length;
+    } while (cursor !== "0");
+    if (migratedKeys > 0) {
+      await this.client.del(legacyKey);
+    }
+    return { migratedKeys };
+  }
   async scanIndexKeys() {
     const matches = [];
     let cursor = "0";
@@ -365,12 +442,40 @@ var RedisTagIndex = class {
     }
     return `${this.prefix}:keys:${simpleHash(key) % this.knownKeysShards}`;
   }
+  async knownKeysKeysForRead() {
+    if (this.knownKeysShards === 1) {
+      return [this.legacyKnownKeysKey()];
+    }
+    const shardedKeys = this.knownKeysKeys();
+    const legacyKey = this.legacyKnownKeysKey();
+    const legacyExists = await this.client.exists(legacyKey) > 0;
+    if (!legacyExists) {
+      return shardedKeys;
+    }
+    this.warnLegacyKnownKeys(legacyKey);
+    return [legacyKey, ...shardedKeys];
+  }
   knownKeysKeys() {
     if (this.knownKeysShards === 1) {
       return [`${this.prefix}:keys`];
     }
     return Array.from({ length: this.knownKeysShards }, (_, index) => `${this.prefix}:keys:${index}`);
   }
+  legacyKnownKeysKey() {
+    return `${this.prefix}:keys`;
+  }
+  warnLegacyKnownKeys(legacyKey) {
+    if (this.warnedLegacyKnownKeys) {
+      return;
+    }
+    this.warnedLegacyKnownKeys = true;
+    const message = "RedisTagIndex detected a legacy RedisTagIndex known-key set. Run `layercache migrate-tag-index` to migrate keys into the sharded layout.";
+    if (this.logger?.warn) {
+      this.logger.warn(message, { legacyKey, knownKeysShards: this.knownKeysShards });
+      return;
+    }
+    console.warn(`[layercache] ${message}`, { legacyKey, knownKeysShards: this.knownKeysShards });
+  }
   keyTagsKey(key) {
     return `${this.prefix}:key:${encodeURIComponent(key)}`;
   }
@@ -380,7 +485,7 @@ var RedisTagIndex = class {
 };
 function normalizeKnownKeysShards(value) {
   if (value === void 0) {
-    return 1;
+    return DEFAULT_KNOWN_KEYS_SHARDS;
   }
   if (!Number.isInteger(value) || value <= 0) {
     throw new Error("RedisTagIndex.knownKeysShards must be a positive integer.");
@@ -398,7 +503,11 @@ function simpleHash(value) {
 // src/cli.ts
 var CONNECT_TIMEOUT_MS = 5e3;
 async function main(argv = process.argv.slice(2)) {
+  process.exitCode = void 0;
   const args = parseArgs(argv);
+  if (args.parseError) {
+    return;
+  }
   if (!args.command || !args.redisUrl) {
     printUsage();
     process.exitCode = 1;
@@ -418,6 +527,13 @@ async function main(argv = process.argv.slice(2)) {
       process.exitCode = 1;
       return;
     }
+    if (process.env.NODE_ENV === "production" && !args.allowPlaintext) {
+      process.stderr.write(
+        "Error: refusing plaintext redis:// connection because NODE_ENV=production. Use rediss:// for TLS-encrypted connections, or pass --allow-plaintext to explicitly override.\n"
+      );
+      process.exitCode = 1;
+      return;
+    }
     process.stderr.write(
       "Warning: connecting to Redis without TLS (redis://). All data including cached values and credentials will be transmitted in plaintext. Use rediss:// in production environments, or set --require-tls.\n"
     );
@@ -435,7 +551,7 @@ async function main(argv = process.argv.slice(2)) {
     if (args.command === "stats") {
       const pattern = args.pattern ?? "*";
       if (args.pattern && !validateCliInput(args.pattern, validatePattern)) return;
-      const keys = await scanKeys(redis, pattern);
+      const keys = await scanKeys(redis, pattern, args.scanLimit ?? DEFAULT_SCAN_MAX_KEYS);
       process.stdout.write(`${JSON.stringify({ totalKeys: keys.length, pattern }, null, 2)}
 `);
       return;
@@ -443,7 +559,7 @@ async function main(argv = process.argv.slice(2)) {
     if (args.command === "keys") {
       const pattern = args.pattern ?? "*";
       if (args.pattern && !validateCliInput(args.pattern, validatePattern)) return;
-      const keys = await scanKeys(redis, pattern);
+      const keys = await scanKeys(redis, pattern, args.scanLimit ?? DEFAULT_SCAN_MAX_KEYS);
       if (keys.length > 0) {
         process.stdout.write(`${keys.join("\n")}
 `);
@@ -464,7 +580,7 @@ async function main(argv = process.argv.slice(2)) {
       }
       const effectivePattern = args.pattern ?? "*";
       if (args.pattern && !validateCliInput(args.pattern, validatePattern)) return;
-      const keys = await scanKeys(redis, effectivePattern);
+      const keys = await scanKeys(redis, effectivePattern, args.scanLimit ?? DEFAULT_SCAN_MAX_KEYS);
       if (!args.pattern && !args.force && keys.length > 0) {
         process.stderr.write(`Warning: this operation will invalidate ${keys.length} keys. Use --force to confirm.
 `);
@@ -474,6 +590,17 @@ async function main(argv = process.argv.slice(2)) {
         await batchDelete(redis, keys);
       }
       process.stdout.write(`${JSON.stringify({ deletedKeys: keys.length, pattern: effectivePattern }, null, 2)}
+`);
+      return;
+    }
+    if (args.command === "migrate-tag-index") {
+      const tagIndex = new RedisTagIndex({
+        client: redis,
+        prefix: args.tagIndexPrefix ?? "layercache:tag-index",
+        knownKeysShards: args.knownKeysShards
+      });
+      const result = await tagIndex.migrateLegacyKnownKeys();
+      process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
       return;
     }
@@ -538,6 +665,7 @@ function parseArgs(argv) {
       if (!value || value.startsWith("--")) {
         process.stderr.write("Error: --redis requires a value (e.g. redis://localhost:6379)\n");
         process.exitCode = 1;
+        parsed.parseError = true;
         return parsed;
       }
       parsed.redisUrl = value;
@@ -554,8 +682,42 @@ function parseArgs(argv) {
     } else if (token === "--tag-index-prefix") {
       parsed.tagIndexPrefix = value;
       index += 1;
+    } else if (token === "--known-key-shards") {
+      if (!value || value.startsWith("--")) {
+        process.stderr.write("Error: --known-key-shards requires a positive integer value.\n");
+        process.exitCode = 1;
+        parsed.parseError = true;
+        return parsed;
+      }
+      const knownKeysShards = Number(value);
+      if (!Number.isSafeInteger(knownKeysShards) || knownKeysShards <= 0) {
+        process.stderr.write("Error: --known-key-shards requires a positive integer value.\n");
+        process.exitCode = 1;
+        parsed.parseError = true;
+        return parsed;
+      }
+      parsed.knownKeysShards = knownKeysShards;
+      index += 1;
+    } else if (token === "--limit") {
+      if (!value || value.startsWith("--")) {
+        process.stderr.write("Error: --limit requires a positive integer value.\n");
+        process.exitCode = 1;
+        parsed.parseError = true;
+        return parsed;
+      }
+      const limit = Number(value);
+      if (!Number.isSafeInteger(limit) || limit <= 0) {
+        process.stderr.write("Error: --limit requires a positive integer value.\n");
+        process.exitCode = 1;
+        parsed.parseError = true;
+        return parsed;
+      }
+      parsed.scanLimit = limit;
+      index += 1;
     } else if (token === "--require-tls") {
       parsed.requireTls = true;
+    } else if (token === "--allow-plaintext") {
+      parsed.allowPlaintext = true;
     } else if (token === "--force") {
       parsed.force = true;
     }
@@ -563,25 +725,24 @@ function parseArgs(argv) {
   return parsed;
 }
 var BATCH_DELETE_SIZE = 500;
-var SCAN_MAX_KEYS = 1e6;
+var DEFAULT_SCAN_MAX_KEYS = 1e5;
 async function batchDelete(redis, keys) {
   for (let i = 0; i < keys.length; i += BATCH_DELETE_SIZE) {
     const batch = keys.slice(i, i + BATCH_DELETE_SIZE);
     await redis.del(...batch);
   }
 }
-async function scanKeys(redis, pattern) {
+async function scanKeys(redis, pattern, limit) {
   const keys = [];
   let cursor = "0";
   do {
     const [nextCursor, batch] = await redis.scan(cursor, "MATCH", pattern, "COUNT", 100);
     cursor = nextCursor;
-    keys.push(...batch);
-    if (keys.length >= SCAN_MAX_KEYS) {
-      process.stderr.write(
-        `Warning: stopped scanning after ${SCAN_MAX_KEYS} keys. Use a more specific --pattern to narrow results.
-`
-      );
+    const remaining = limit - keys.length;
+    keys.push(...batch.slice(0, remaining));
+    if (keys.length >= limit) {
+      process.stderr.write(`Warning: stopped scanning after ${limit} keys. Use --limit to raise the scan cap.
+`);
       return keys;
     }
   } while (cursor !== "0");
@@ -589,7 +750,7 @@ async function scanKeys(redis, pattern) {
 }
 function printUsage() {
   process.stdout.write(
-    "Usage:\n  layercache stats --redis <url> [--pattern <glob>]\n  layercache keys --redis <url> [--pattern <glob>]\n  layercache inspect --redis <url> --key <key>\n  layercache invalidate --redis <url> [--pattern <glob> | --tag <tag>] [--tag-index-prefix <prefix>]\n\nOptions:\n  --redis <url>               Redis connection URL (e.g. redis://localhost:6379)\n  --pattern <glob>            Glob pattern to filter keys (default: *)\n  --key <key>                 Exact cache key to inspect\n  --tag <tag>                 Invalidate by tag name\n  --tag-index-prefix <prefix> Redis key prefix for tag index (default: layercache:tag-index)\n  --require-tls               Reject non-TLS (redis://) connections\n"
+    "Usage:\n  layercache stats --redis <url> [--pattern <glob>]\n  layercache keys --redis <url> [--pattern <glob>]\n  layercache inspect --redis <url> --key <key>\n  layercache invalidate --redis <url> [--pattern <glob> | --tag <tag>] [--tag-index-prefix <prefix>]\n  layercache migrate-tag-index --redis <url> [--tag-index-prefix <prefix>] [--known-key-shards <count>]\n\nOptions:\n  --redis <url>               Redis connection URL (e.g. redis://localhost:6379)\n  --pattern <glob>            Glob pattern to filter keys (default: *)\n  --key <key>                 Exact cache key to inspect\n  --tag <tag>                 Invalidate by tag name\n  --tag-index-prefix <prefix> Redis key prefix for tag index (default: layercache:tag-index)\n  --known-key-shards <count>  Shard count for RedisTagIndex migration (default: 16)\n  --limit <count>             Maximum Redis keys to scan (default: 100000)\n  --require-tls               Reject non-TLS (redis://) connections\n  --allow-plaintext          Explicitly allow redis:// when NODE_ENV=production\n"
   );
 }
 function decodeInspectablePayload(payload) {

package/dist/cli.js

@@ -4,7 +4,7 @@ import {
   validateCacheKey,
   validatePattern,
   validateTag
-} from "./chunk-7KMKQ6QZ.js";
+} from "./chunk-NBMG7DHT.js";
 import {
   isStoredValueEnvelope,
   resolveStoredValue
@@ -14,7 +14,11 @@ import {
 import Redis from "ioredis";
 var CONNECT_TIMEOUT_MS = 5e3;
 async function main(argv = process.argv.slice(2)) {
+  process.exitCode = void 0;
   const args = parseArgs(argv);
+  if (args.parseError) {
+    return;
+  }
   if (!args.command || !args.redisUrl) {
     printUsage();
     process.exitCode = 1;
@@ -34,6 +38,13 @@ async function main(argv = process.argv.slice(2)) {
       process.exitCode = 1;
       return;
     }
+    if (process.env.NODE_ENV === "production" && !args.allowPlaintext) {
+      process.stderr.write(
+        "Error: refusing plaintext redis:// connection because NODE_ENV=production. Use rediss:// for TLS-encrypted connections, or pass --allow-plaintext to explicitly override.\n"
+      );
+      process.exitCode = 1;
+      return;
+    }
     process.stderr.write(
       "Warning: connecting to Redis without TLS (redis://). All data including cached values and credentials will be transmitted in plaintext. Use rediss:// in production environments, or set --require-tls.\n"
     );
@@ -51,7 +62,7 @@ async function main(argv = process.argv.slice(2)) {
     if (args.command === "stats") {
       const pattern = args.pattern ?? "*";
       if (args.pattern && !validateCliInput(args.pattern, validatePattern)) return;
-      const keys = await scanKeys(redis, pattern);
+      const keys = await scanKeys(redis, pattern, args.scanLimit ?? DEFAULT_SCAN_MAX_KEYS);
       process.stdout.write(`${JSON.stringify({ totalKeys: keys.length, pattern }, null, 2)}
 `);
       return;
@@ -59,7 +70,7 @@ async function main(argv = process.argv.slice(2)) {
     if (args.command === "keys") {
       const pattern = args.pattern ?? "*";
       if (args.pattern && !validateCliInput(args.pattern, validatePattern)) return;
-      const keys = await scanKeys(redis, pattern);
+      const keys = await scanKeys(redis, pattern, args.scanLimit ?? DEFAULT_SCAN_MAX_KEYS);
       if (keys.length > 0) {
         process.stdout.write(`${keys.join("\n")}
 `);
@@ -80,7 +91,7 @@ async function main(argv = process.argv.slice(2)) {
       }
       const effectivePattern = args.pattern ?? "*";
       if (args.pattern && !validateCliInput(args.pattern, validatePattern)) return;
-      const keys = await scanKeys(redis, effectivePattern);
+      const keys = await scanKeys(redis, effectivePattern, args.scanLimit ?? DEFAULT_SCAN_MAX_KEYS);
       if (!args.pattern && !args.force && keys.length > 0) {
         process.stderr.write(`Warning: this operation will invalidate ${keys.length} keys. Use --force to confirm.
 `);
@@ -90,6 +101,17 @@ async function main(argv = process.argv.slice(2)) {
         await batchDelete(redis, keys);
       }
       process.stdout.write(`${JSON.stringify({ deletedKeys: keys.length, pattern: effectivePattern }, null, 2)}
+`);
+      return;
+    }
+    if (args.command === "migrate-tag-index") {
+      const tagIndex = new RedisTagIndex({
+        client: redis,
+        prefix: args.tagIndexPrefix ?? "layercache:tag-index",
+        knownKeysShards: args.knownKeysShards
+      });
+      const result = await tagIndex.migrateLegacyKnownKeys();
+      process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
       return;
     }
@@ -154,6 +176,7 @@ function parseArgs(argv) {
       if (!value || value.startsWith("--")) {
         process.stderr.write("Error: --redis requires a value (e.g. redis://localhost:6379)\n");
         process.exitCode = 1;
+        parsed.parseError = true;
         return parsed;
       }
       parsed.redisUrl = value;
@@ -170,8 +193,42 @@ function parseArgs(argv) {
     } else if (token === "--tag-index-prefix") {
       parsed.tagIndexPrefix = value;
       index += 1;
+    } else if (token === "--known-key-shards") {
+      if (!value || value.startsWith("--")) {
+        process.stderr.write("Error: --known-key-shards requires a positive integer value.\n");
+        process.exitCode = 1;
+        parsed.parseError = true;
+        return parsed;
+      }
+      const knownKeysShards = Number(value);
+      if (!Number.isSafeInteger(knownKeysShards) || knownKeysShards <= 0) {
+        process.stderr.write("Error: --known-key-shards requires a positive integer value.\n");
+        process.exitCode = 1;
+        parsed.parseError = true;
+        return parsed;
+      }
+      parsed.knownKeysShards = knownKeysShards;
+      index += 1;
+    } else if (token === "--limit") {
+      if (!value || value.startsWith("--")) {
+        process.stderr.write("Error: --limit requires a positive integer value.\n");
+        process.exitCode = 1;
+        parsed.parseError = true;
+        return parsed;
+      }
+      const limit = Number(value);
+      if (!Number.isSafeInteger(limit) || limit <= 0) {
+        process.stderr.write("Error: --limit requires a positive integer value.\n");
+        process.exitCode = 1;
+        parsed.parseError = true;
+        return parsed;
+      }
+      parsed.scanLimit = limit;
+      index += 1;
     } else if (token === "--require-tls") {
       parsed.requireTls = true;
+    } else if (token === "--allow-plaintext") {
+      parsed.allowPlaintext = true;
     } else if (token === "--force") {
       parsed.force = true;
     }
@@ -179,25 +236,24 @@ function parseArgs(argv) {
   return parsed;
 }
 var BATCH_DELETE_SIZE = 500;
-var SCAN_MAX_KEYS = 1e6;
+var DEFAULT_SCAN_MAX_KEYS = 1e5;
 async function batchDelete(redis, keys) {
   for (let i = 0; i < keys.length; i += BATCH_DELETE_SIZE) {
     const batch = keys.slice(i, i + BATCH_DELETE_SIZE);
     await redis.del(...batch);
   }
 }
-async function scanKeys(redis, pattern) {
+async function scanKeys(redis, pattern, limit) {
   const keys = [];
   let cursor = "0";
   do {
     const [nextCursor, batch] = await redis.scan(cursor, "MATCH", pattern, "COUNT", 100);
     cursor = nextCursor;
-    keys.push(...batch);
-    if (keys.length >= SCAN_MAX_KEYS) {
-      process.stderr.write(
-        `Warning: stopped scanning after ${SCAN_MAX_KEYS} keys. Use a more specific --pattern to narrow results.
-`
-      );
+    const remaining = limit - keys.length;
+    keys.push(...batch.slice(0, remaining));
+    if (keys.length >= limit) {
+      process.stderr.write(`Warning: stopped scanning after ${limit} keys. Use --limit to raise the scan cap.
+`);
       return keys;
     }
   } while (cursor !== "0");
@@ -205,7 +261,7 @@ async function scanKeys(redis, pattern) {
 }
 function printUsage() {
   process.stdout.write(
-    "Usage:\n  layercache stats --redis <url> [--pattern <glob>]\n  layercache keys --redis <url> [--pattern <glob>]\n  layercache inspect --redis <url> --key <key>\n  layercache invalidate --redis <url> [--pattern <glob> | --tag <tag>] [--tag-index-prefix <prefix>]\n\nOptions:\n  --redis <url>               Redis connection URL (e.g. redis://localhost:6379)\n  --pattern <glob>            Glob pattern to filter keys (default: *)\n  --key <key>                 Exact cache key to inspect\n  --tag <tag>                 Invalidate by tag name\n  --tag-index-prefix <prefix> Redis key prefix for tag index (default: layercache:tag-index)\n  --require-tls               Reject non-TLS (redis://) connections\n"
+    "Usage:\n  layercache stats --redis <url> [--pattern <glob>]\n  layercache keys --redis <url> [--pattern <glob>]\n  layercache inspect --redis <url> --key <key>\n  layercache invalidate --redis <url> [--pattern <glob> | --tag <tag>] [--tag-index-prefix <prefix>]\n  layercache migrate-tag-index --redis <url> [--tag-index-prefix <prefix>] [--known-key-shards <count>]\n\nOptions:\n  --redis <url>               Redis connection URL (e.g. redis://localhost:6379)\n  --pattern <glob>            Glob pattern to filter keys (default: *)\n  --key <key>                 Exact cache key to inspect\n  --tag <tag>                 Invalidate by tag name\n  --tag-index-prefix <prefix> Redis key prefix for tag index (default: layercache:tag-index)\n  --known-key-shards <count>  Shard count for RedisTagIndex migration (default: 16)\n  --limit <count>             Maximum Redis keys to scan (default: 100000)\n  --require-tls               Reject non-TLS (redis://) connections\n  --allow-plaintext          Explicitly allow redis:// when NODE_ENV=production\n"
   );
 }
 function decodeInspectablePayload(payload) {