@coopenomics/parser 1.0.0

package/dist/cli/index.js

@@ -0,0 +1,951 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { Command } from "commander";
+
+// src/config/index.ts
+import { readFileSync } from "fs";
+import { parse as parseYaml } from "yaml";
+
+// src/errors.ts
+var ConfigValidationError = class extends Error {
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.name = "ConfigValidationError";
+    this.cause = cause;
+  }
+};
+var ConfigSecurityError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigSecurityError";
+  }
+};
+
+// src/config/index.ts
+var PLAIN_SECRET_RE = /redis:\/\/[^$\s]*:[^@$\s]+@/i;
+function interpolateEnv(value) {
+  return value.replace(/\$\{([^}]+)\}/g, (_, varName) => {
+    return process.env[varName] ?? `\${${varName}}`;
+  });
+}
+function interpolateDeep(obj) {
+  if (typeof obj === "string") return interpolateEnv(obj);
+  if (Array.isArray(obj)) return obj.map(interpolateDeep);
+  if (obj !== null && typeof obj === "object") {
+    const result = {};
+    for (const [k, v] of Object.entries(obj)) {
+      result[k] = interpolateDeep(v);
+    }
+    return result;
+  }
+  return obj;
+}
+function isObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function validate(raw) {
+  const errors = [];
+  if (!isObject(raw)) {
+    errors.push("(root) must be an object");
+    throw new ConfigValidationError(`Config validation failed: ${errors.join("; ")}`);
+  }
+  if (!isObject(raw["ship"]) || typeof raw["ship"]["url"] !== "string") {
+    errors.push("ship.url is required and must be a string");
+  }
+  if (!isObject(raw["redis"]) || typeof raw["redis"]["url"] !== "string") {
+    errors.push("redis.url is required and must be a string");
+  }
+  const abiFallback = raw["abiFallback"];
+  if (abiFallback !== void 0 && abiFallback !== "rpc-current" && abiFallback !== "fail") {
+    errors.push('abiFallback must be "rpc-current" or "fail"');
+  }
+  const deserializer = raw["deserializer"];
+  if (deserializer !== void 0 && deserializer !== "wharfkit") {
+    errors.push('deserializer must be "wharfkit"');
+  }
+  if (errors.length > 0) {
+    throw new ConfigValidationError(`Config validation failed: ${errors.join("; ")}`);
+  }
+  return true;
+}
+function checkPlainSecrets(opts) {
+  if (PLAIN_SECRET_RE.test(opts.redis.url)) {
+    throw new ConfigSecurityError(
+      "Secrets must be injected via env variables, not hardcoded in config"
+    );
+  }
+}
+function parseConfig(raw) {
+  const interpolated = interpolateDeep(raw);
+  validate(interpolated);
+  const opts = interpolated;
+  checkPlainSecrets(opts);
+  return opts;
+}
+function fromConfigFile(filePath) {
+  const text = readFileSync(filePath, "utf8");
+  const raw = parseYaml(text);
+  return parseConfig(raw);
+}
+
+// src/adapters/IoRedisStore.ts
+var { default: RedisClass } = await import("ioredis");
+var PEXPIRE_LUA = `
+local current = redis.call('GET', KEYS[1])
+if current == ARGV[2] then
+  redis.call('PEXPIRE', KEYS[1], ARGV[1])
+  return 1
+end
+return 0
+`;
+var DEL_LUA = `
+local current = redis.call('GET', KEYS[1])
+if current == ARGV[1] then
+  redis.call('DEL', KEYS[1])
+  return 1
+end
+return 0
+`;
+function parseStreamEntries(raw) {
+  const messages = [];
+  for (const [msgId, rawFields] of raw) {
+    const fields = {};
+    for (let i = 0; i + 1 < rawFields.length; i += 2) {
+      fields[rawFields[i] ?? ""] = rawFields[i + 1] ?? "";
+    }
+    messages.push({ id: msgId, fields });
+  }
+  return messages;
+}
+function parseXGroupInfo(raw) {
+  let obj;
+  if (Array.isArray(raw)) {
+    obj = {};
+    for (let i = 0; i + 1 < raw.length; i += 2) {
+      obj[raw[i]] = raw[i + 1];
+    }
+  } else {
+    obj = raw;
+  }
+  return {
+    name: String(obj["name"] ?? ""),
+    pending: Number(obj["pending"] ?? 0),
+    // Поле 'last-delivered-id' в Redis (с дефисами), не 'lastDeliveredId'
+    lastDeliveredId: String(obj["last-delivered-id"] ?? "0-0"),
+    // lag появилось в Redis 7.0; null для старых версий
+    lag: obj["lag"] != null ? Number(obj["lag"]) : null,
+    consumers: Number(obj["consumers"] ?? 0)
+  };
+}
+var IoRedisStore = class {
+  /** Прямой доступ к ioredis-клиенту (для тестов и расширения). */
+  client;
+  constructor(opts) {
+    const redisOpts = {
+      lazyConnect: true,
+      // не подключаться в конструкторе — явный connect()
+      enableReadyCheck: true
+      // проверять готовность перед командами
+    };
+    if (opts.password !== void 0) redisOpts.password = opts.password;
+    if (opts.keyPrefix !== void 0) redisOpts.keyPrefix = opts.keyPrefix;
+    this.client = new RedisClass(opts.url, redisOpts);
+  }
+  /** Явное подключение — вызывается один раз при старте Parser/ParserClient. */
+  async connect() {
+    await this.client.connect();
+  }
+  /** XADD stream * field1 val1 … — возвращает присвоенный entry ID. */
+  async xadd(stream, fields) {
+    const args = [];
+    for (const [k, v] of Object.entries(fields)) args.push(k, v);
+    const id = await this.client.xadd(stream, "*", ...args);
+    return id ?? "";
+  }
+  /** XTRIM stream MINID minId — удаляет записи с ID < minId. */
+  async xtrim(stream, minId) {
+    return this.client.xtrim(stream, "MINID", minId);
+  }
+  /**
+   * XGROUP CREATE stream group startId MKSTREAM
+   * MKSTREAM: создаёт стрим если не существует.
+   * BUSYGROUP: группа уже существует — это нормально, поглощаем ошибку.
+   */
+  async xgroupCreate(stream, group, startId) {
+    try {
+      await this.client.xgroup("CREATE", stream, group, startId, "MKSTREAM");
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("BUSYGROUP")) return;
+      throw err;
+    }
+  }
+  /** XGROUP SETID stream group id — переставляет позицию group в стриме. */
+  async xgroupSetId(stream, group, id) {
+    await this.client.xgroup("SETID", stream, group, id);
+  }
+  /** XINFO GROUPS stream → список consumer groups с метриками. */
+  async xinfoGroups(stream) {
+    const raw = await this.client.xinfo("GROUPS", stream);
+    return (raw ?? []).map(parseXGroupInfo);
+  }
+  /**
+   * XREADGROUP GROUP group consumer COUNT count BLOCK blockMs STREAMS stream id
+   * id='>' — только новые сообщения.
+   * id='0' — PEL (pending): уже доставленные, но не подтверждённые (recovery).
+   */
+  async xreadGroup(stream, group, consumer, count, blockMs, id) {
+    const result = await this.client.xreadgroup(
+      "GROUP",
+      group,
+      consumer,
+      "COUNT",
+      count,
+      "BLOCK",
+      blockMs,
+      "STREAMS",
+      stream,
+      id
+    );
+    if (!result) return [];
+    const messages = [];
+    for (const [, entries] of result) {
+      messages.push(...parseStreamEntries(entries));
+    }
+    return messages;
+  }
+  /** XRANGE stream start end COUNT count. */
+  async xrange(stream, start, end, count) {
+    const raw = await this.client.xrange(stream, start, end, "COUNT", count);
+    return parseStreamEntries(raw);
+  }
+  /** XREVRANGE stream end start COUNT count. */
+  async xrevrange(stream, end, start, count) {
+    const raw = await this.client.xrevrange(stream, end, start, "COUNT", count);
+    return parseStreamEntries(raw);
+  }
+  /** XLEN stream. */
+  async xlen(stream) {
+    return this.client.xlen(stream);
+  }
+  /** XDEL stream id — удаляет запись по ID. */
+  async xdel(stream, id) {
+    return this.client.xdel(stream, id);
+  }
+  /** XACK stream group id — убирает из PEL. */
+  async xack(stream, group, id) {
+    await this.client.xack(stream, group, id);
+  }
+  /** ZADD key score member. */
+  async zadd(key, score, member) {
+    await this.client.zadd(key, score, member);
+  }
+  /**
+   * ZREVRANGEBYSCORE key max min LIMIT 0 1
+   * Возвращает максимум один элемент с score ≤ max.
+   * Используется для поиска ABI: «последняя версия не позже блока N».
+   */
+  async zrangeByscoreRev(key, max, min) {
+    return this.client.zrevrangebyscore(key, max, min, "LIMIT", 0, 1);
+  }
+  /** ZRANGEBYSCORE key min max LIMIT 0 9999999 — все элементы в диапазоне. */
+  async zrangeByScore(key, min, max) {
+    return this.client.zrangebyscore(key, min, max, "LIMIT", 0, 9999999);
+  }
+  /** ZCOUNT key min max. */
+  async zcount(key, min, max) {
+    return this.client.zcount(key, min, max);
+  }
+  /** ZREMRANGEBYSCORE key min max → число удалённых. */
+  async zremRangeByScore(key, min, max) {
+    return this.client.zremrangebyscore(key, min, max);
+  }
+  /** ZCARD key. */
+  async zcard(key) {
+    return this.client.zcard(key);
+  }
+  /** HSET key field1 val1 field2 val2 … */
+  async hset(key, fields) {
+    const args = [];
+    for (const [k, v] of Object.entries(fields)) args.push(k, v);
+    if (args.length > 0) await this.client.hset(key, ...args);
+  }
+  /** HGET key field. */
+  async hget(key, field) {
+    return this.client.hget(key, field);
+  }
+  /** HGETALL key → пустой объект если ключ не существует (ioredis возвращает null). */
+  async hgetAll(key) {
+    const result = await this.client.hgetall(key);
+    return result ?? {};
+  }
+  /** HINCRBY key field increment → новое значение счётчика. */
+  async hincrby(key, field, increment) {
+    return this.client.hincrby(key, field, increment);
+  }
+  /** HDEL key field. */
+  async hdel(key, field) {
+    await this.client.hdel(key, field);
+  }
+  /**
+   * SET key value NX PX pxMs
+   * NX: только если не существует. PX: TTL в миллисекундах.
+   * Используется для захвата distributed lock'а.
+   */
+  async setNx(key, value, pxMs) {
+    const result = await this.client.set(key, value, "NX", "PX", pxMs);
+    return result === "OK";
+  }
+  /**
+   * Выполняет PEXPIRE_LUA: продлевает TTL lock'а только если мы — владелец.
+   * Возвращает true если продление прошло успешно.
+   */
+  async pexpire(key, ms, value) {
+    const result = await this.client.eval(PEXPIRE_LUA, 1, key, String(ms), value);
+    return result === 1;
+  }
+  /**
+   * Выполняет DEL_LUA: удаляет lock только если мы — владелец.
+   * Возвращает true если удаление прошло успешно.
+   */
+  async luaDel(key, value) {
+    const result = await this.client.eval(DEL_LUA, 1, key, value);
+    return result === 1;
+  }
+  /** EXPIRE key seconds. */
+  async expire(key, seconds) {
+    await this.client.expire(key, seconds);
+  }
+  /**
+   * Полный SCAN по паттерну: итерирует cursor пока не вернётся '0'.
+   * @param count — подсказка Redis сколько ключей возвращать за итерацию.
+   * @returns Полный список ключей (может быть большим для широких паттернов).
+   */
+  async scan(pattern, count = 100) {
+    const keys = [];
+    let cursor = "0";
+    do {
+      const [nextCursor, batch] = await this.client.scan(cursor, "MATCH", pattern, "COUNT", count);
+      keys.push(...batch);
+      cursor = nextCursor;
+    } while (cursor !== "0");
+    return keys;
+  }
+  /** Закрывает соединение с Redis. */
+  async quit() {
+    await this.client.quit();
+  }
+};
+
+// src/redis/keys.ts
+var RedisKeys = {
+  /**
+   * Главный поток событий парсера (unified event stream).
+   * Тип Redis: Stream. Тримируется XtrimSupervisor'ом.
+   * Пример: ce:parser:eos-mainnet:events
+   */
+  eventsStream: (chainId) => `ce:parser:${chainId}:events`,
+  /**
+   * Dead-letter поток для конкретной подписки.
+   * Содержит сообщения, которые не смог обработать consumer после N попыток.
+   * Тип Redis: Stream.
+   * Пример: ce:parser:eos-mainnet:dead:verifier
+   */
+  deadLetterStream: (chainId, subId) => `ce:parser:${chainId}:dead:${subId}`,
+  /**
+   * Поток для задания on-demand reparse (зарезервировано для будущего).
+   * Тип Redis: Stream.
+   */
+  reparseStream: (chainId, jobId) => `ce:parser:${chainId}:reparse:${jobId}`,
+  /**
+   * История версий ABI конкретного контракта.
+   * Тип Redis: Sorted Set. Score = block_num, member = base64(rawAbiBytes).
+   * При поиске ABI для блока N используется ZREVRANGEBYSCORE … N -inf LIMIT 0 1.
+   * Пример: parser:abi:eosio.token
+   */
+  abiZset: (contract) => `parser:abi:${contract}`,
+  /**
+   * Контрольная точка синхронизации парсера (crash-recovery).
+   * Тип Redis: Hash. Поля: block_num, block_id, last_updated.
+   * При рестарте парсер читает отсюда позицию и продолжает с неё.
+   */
+  syncHash: (chainId) => `parser:sync:${chainId}`,
+  /**
+   * Реестр всех зарегистрированных подписок.
+   * Тип Redis: Hash. Ключ поля = subId, значение = JSON-метаданные подписки.
+   */
+  subsHash: () => `parser:subs`,
+  /**
+   * Счётчики ошибок per-event для конкретной подписки.
+   * Тип Redis: Hash. Ключ поля = event_id, значение = число провалов.
+   * TTL: 24 часа (обновляется при каждом новом провале).
+   * Используется FailureTracker для решения о переводе в dead-letter.
+   */
+  subFailuresHash: (subId) => `parser:sub:${subId}:failures`,
+  /**
+   * Блокировка single-active-consumer для подписки.
+   * Тип Redis: String (instanceId держателя блокировки). TTL: 10 с (автопродление).
+   * Только один экземпляр consumer-а может быть active; остальные — standby.
+   */
+  subLock: (subId) => `parser:sub:${subId}:lock`,
+  /**
+   * Метаданные задания reparse (зарезервировано для будущего).
+   * Тип Redis: Hash.
+   */
+  reparseJobHash: (jobId) => `parser:reparse:${jobId}`
+};
+
+// src/cli/commands/listSubscriptions.ts
+function formatFilters(filters) {
+  if (!filters || filters.length === 0) return "*";
+  return filters.slice(0, 2).map((f) => {
+    const kind = f["kind"] ?? "*";
+    if (kind === "action") return `action:${f["account"] ?? "*"}/${f["name"] ?? "*"}`;
+    if (kind === "delta") return `delta:${f["code"] ?? "*"}`;
+    if (kind === "native-delta") return `native-delta:${f["table"] ?? "*"}`;
+    return kind;
+  }).join(",");
+}
+async function listSubscriptions(redis, chainId, json) {
+  const allSubs = await redis.hgetAll(RedisKeys.subsHash());
+  if (Object.keys(allSubs).length === 0) {
+    console.log("No subscriptions registered.");
+    return;
+  }
+  const stream = RedisKeys.eventsStream(chainId);
+  let groups = [];
+  try {
+    groups = await redis.xinfoGroups(stream);
+  } catch {
+  }
+  const results = [];
+  for (const rawJson of Object.values(allSubs)) {
+    let meta;
+    try {
+      meta = JSON.parse(rawJson);
+    } catch {
+      continue;
+    }
+    const group = groups.find((g) => g.name === meta.subId);
+    results.push({
+      subId: meta.subId,
+      filters: meta.filters,
+      startFrom: String(meta.startFrom),
+      registeredAt: meta.registeredAt ?? "",
+      pending: group !== void 0 ? group.pending : null,
+      lag: group !== void 0 ? group.lag : null,
+      lastDeliveredId: group?.lastDeliveredId ?? "not started"
+    });
+  }
+  if (json) {
+    console.log(JSON.stringify(results, null, 2));
+    return;
+  }
+  const cols = {
+    subId: 16,
+    filters: 25,
+    pending: 9,
+    lag: 6,
+    lastDelivered: 21,
+    startFrom: 10
+  };
+  const header = "SUB ID".padEnd(cols.subId) + "FILTERS".padEnd(cols.filters) + "PENDING".padEnd(cols.pending) + "LAG".padEnd(cols.lag) + "LAST DELIVERED".padEnd(cols.lastDelivered) + "START FROM";
+  console.log(header);
+  console.log("-".repeat(header.length));
+  for (const sub of results) {
+    const row = sub.subId.slice(0, cols.subId - 1).padEnd(cols.subId) + formatFilters(sub.filters).slice(0, cols.filters - 1).padEnd(cols.filters) + String(sub.pending ?? "-").padEnd(cols.pending) + String(sub.lag ?? "-").padEnd(cols.lag) + sub.lastDeliveredId.slice(0, cols.lastDelivered - 1).padEnd(cols.lastDelivered) + sub.startFrom;
+    console.log(row);
+  }
+}
+
+// src/cli/commands/resetSubscription.ts
+async function findSetidForBlock(redis, stream, targetBlock) {
+  let cursor = "-";
+  let lastBeforeTarget = "0-0";
+  while (true) {
+    const entries = await redis.xrange(stream, cursor, "+", 100);
+    if (entries.length === 0) break;
+    for (const entry of entries) {
+      let blockNum;
+      try {
+        const event = JSON.parse(entry.fields["data"] ?? "{}");
+        if (event.block_num !== void 0) blockNum = Number(event.block_num);
+      } catch {
+      }
+      if (blockNum !== void 0) {
+        if (blockNum < targetBlock) {
+          lastBeforeTarget = entry.id;
+        } else {
+          return lastBeforeTarget;
+        }
+      }
+    }
+    if (entries.length < 100) break;
+    const lastId = entries[entries.length - 1].id;
+    cursor = "(" + lastId;
+  }
+  return lastBeforeTarget;
+}
+async function resetSubscription(redis, chainId, subId, toBlock, dryRun) {
+  const stream = RedisKeys.eventsStream(chainId);
+  const groupName = subId;
+  let groups = [];
+  try {
+    groups = await redis.xinfoGroups(stream);
+  } catch {
+    throw new Error(`Subscription ${subId} has no active consumer group. Start the consumer first.`);
+  }
+  const group = groups.find((g) => g.name === groupName);
+  if (!group) {
+    throw new Error(`Subscription ${subId} has no active consumer group. Start the consumer first.`);
+  }
+  const pelCount = group.pending;
+  let targetId;
+  if (toBlock === "0" || toBlock === "latest" || toBlock === "$") {
+    targetId = "$";
+  } else {
+    const blockNum = Number(toBlock);
+    if (isNaN(blockNum) || blockNum < 0) {
+      throw new Error(`Invalid --to-block value: ${toBlock}. Use a block number, 0, or "latest".`);
+    }
+    const firstEntries = await redis.xrange(stream, "-", "+", 1);
+    if (firstEntries.length > 0) {
+      let earliestBlock;
+      try {
+        const event = JSON.parse(firstEntries[0].fields["data"] ?? "{}");
+        if (event.block_num !== void 0) earliestBlock = Number(event.block_num);
+      } catch {
+      }
+      if (earliestBlock !== void 0 && blockNum < earliestBlock) {
+        throw new Error(
+          `Block ${blockNum} is before earliest available block ${earliestBlock} (stream trimmed). Cannot reset to trimmed range.`
+        );
+      }
+    }
+    targetId = await findSetidForBlock(redis, stream, blockNum);
+  }
+  if (dryRun) {
+    console.log(`[dry-run] Would execute: XGROUP SETID ${stream} ${groupName} ${targetId}`);
+    if (pelCount > 0) {
+      console.log(`Warning: PEL has ${pelCount} pending messages. They will be re-delivered on next consumer start.`);
+    }
+    return;
+  }
+  await redis.xgroupSetId(stream, groupName, targetId);
+  console.log(`Reset subscription ${subId} to entry ${targetId}.`);
+  if (pelCount > 0) {
+    console.log(`Warning: PEL has ${pelCount} pending messages. They will be re-delivered on next consumer start.`);
+  }
+}
+
+// src/cli/commands/abiPrune.ts
+async function pruneContract(redis, contract, olderThan, dryRun) {
+  const key = RedisKeys.abiZset(contract);
+  const total = await redis.zcard(key);
+  if (total === 0) {
+    return { pruned: 0, remaining: 0, oldestScore: null, newestScore: null };
+  }
+  const candidateCount = await redis.zcount(key, "-inf", `(${olderThan}`);
+  const remaining = total - candidateCount;
+  if (remaining < 1 && candidateCount > 0) {
+    throw new Error(`Cannot prune all ABI versions for ${contract} \u2014 at least one must remain`);
+  }
+  if (!dryRun && candidateCount > 0) {
+    await redis.zremRangeByScore(key, "-inf", `(${olderThan}`);
+  }
+  return { pruned: dryRun ? 0 : candidateCount, remaining, oldestScore: null, newestScore: null };
+}
+async function abiPrune(redis, contract, olderThan, dryRun, allContracts) {
+  if (!allContracts && !contract) {
+    throw new Error("Specify --contract or --all-contracts");
+  }
+  if (allContracts) {
+    const keys = await redis.scan("parser:abi:*");
+    if (keys.length === 0) {
+      console.log("No ABI history found.");
+      return;
+    }
+    const rows = [];
+    for (const key2 of keys) {
+      const name = key2.replace(/^parser:abi:/, "");
+      try {
+        const result = await pruneContract(redis, name, olderThan, dryRun);
+        rows.push({ contract: name, pruned: dryRun ? result.remaining : result.pruned, remaining: result.remaining });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`  ${name}: ${msg}`);
+      }
+    }
+    if (dryRun) {
+      console.log("CONTRACT".padEnd(30) + "WOULD PRUNE".padEnd(14) + "REMAINING");
+      console.log("-".repeat(54));
+      for (const row of rows) {
+        const candidateCount2 = row.pruned;
+        console.log(row.contract.padEnd(30) + String(candidateCount2).padEnd(14) + row.remaining);
+      }
+    }
+    return;
+  }
+  const key = RedisKeys.abiZset(contract);
+  const total = await redis.zcard(key);
+  if (total === 0) {
+    console.log(`No ABI history found for contract ${contract}.`);
+    return;
+  }
+  const candidateCount = await redis.zcount(key, "-inf", `(${olderThan}`);
+  const remaining = total - candidateCount;
+  if (remaining < 1 && candidateCount > 0) {
+    console.error(`Cannot prune all ABI versions \u2014 at least one must remain`);
+    process.exitCode = 1;
+    return;
+  }
+  if (dryRun) {
+    console.log(`[dry-run] Would prune ${candidateCount} ABI version(s) for ${contract}. ${remaining} version(s) would remain.`);
+    return;
+  }
+  const pruned = candidateCount > 0 ? await redis.zremRangeByScore(key, "-inf", `(${olderThan}`) : 0;
+  const newTotal = await redis.zcard(key);
+  if (pruned === 0) {
+    console.log(`Pruned 0 ABI versions for ${contract}. ${newTotal} version(s) remain.`);
+    return;
+  }
+  console.log(`Pruned ${pruned} ABI version(s) for ${contract}. ${newTotal} version(s) remain.`);
+}
+
+// src/cli/commands/listDeadLetters.ts
+function entryIdToTimestamp(entryId) {
+  const ms = parseInt(entryId.split("-")[0] ?? "0", 10);
+  return new Date(ms).toISOString();
+}
+function truncate(s, max) {
+  return s.length > max ? s.slice(0, max - 1) + "\u2026" : s;
+}
+async function readDeadLetters(redis, stream, limit, fromEntry) {
+  const raw = await redis.xrange(stream, fromEntry, "+", limit);
+  return raw.map((msg) => {
+    let eventId = "";
+    let kind = "";
+    let originalPayload = null;
+    const dataStr = msg.fields["data"];
+    if (dataStr) {
+      try {
+        const parsed = JSON.parse(dataStr);
+        eventId = typeof parsed["event_id"] === "string" ? parsed["event_id"] : "";
+        kind = typeof parsed["kind"] === "string" ? parsed["kind"] : "";
+        originalPayload = parsed;
+      } catch {
+      }
+    }
+    return {
+      entryId: msg.id,
+      eventId,
+      kind,
+      failureCount: parseInt(msg.fields["failureCount"] ?? "0", 10),
+      lastError: msg.fields["lastError"] ?? "",
+      deadLetteredAt: entryIdToTimestamp(msg.id),
+      originalPayload
+    };
+  });
+}
+async function listDeadLetters(redis, chainId, subId, json, limit, fromEntry, all) {
+  let streams = [];
+  if (all) {
+    const pattern = RedisKeys.deadLetterStream(chainId, "*");
+    const keys = await redis.scan(pattern);
+    const prefix = `ce:parser:${chainId}:dead:`;
+    streams = keys.map((k) => ({ key: k, subId: k.slice(prefix.length) }));
+    if (streams.length === 0) {
+      console.log("No dead-letter streams found.");
+      return;
+    }
+  } else {
+    if (!subId) throw new Error("--sub-id is required unless --all is specified");
+    streams = [{ key: RedisKeys.deadLetterStream(chainId, subId), subId }];
+  }
+  if (json) {
+    const allEntries = [];
+    for (const { key, subId: sid } of streams) {
+      const entries = await readDeadLetters(redis, key, limit, fromEntry);
+      allEntries.push(...entries.map((e) => ({ ...e, subId: sid })));
+    }
+    console.log(JSON.stringify(allEntries, null, 2));
+    return;
+  }
+  for (const { key, subId: sid } of streams) {
+    const total = await redis.xlen(key);
+    console.log(`Dead letters for ${sid}: ${total} total`);
+    if (total === 0) {
+      console.log(`No dead letters for subscription ${sid}.`);
+      continue;
+    }
+    const entries = await readDeadLetters(redis, key, limit, fromEntry);
+    if (entries.length === 0) {
+      console.log(`No dead letters for subscription ${sid}.`);
+      continue;
+    }
+    const cols = {
+      entryId: 22,
+      eventId: 50,
+      kind: 14,
+      failCount: 6,
+      lastError: 40
+    };
+    if (all) {
+      const subCol = 12;
+      console.log(
+        "SUB ID".padEnd(subCol) + "ENTRY ID".padEnd(cols.entryId) + "EVENT ID".padEnd(cols.eventId) + "KIND".padEnd(cols.kind) + "FAIL#".padEnd(cols.failCount) + "LAST ERROR"
+      );
+      for (const e of entries) {
+        console.log(
+          truncate(sid, subCol).padEnd(subCol) + truncate(e.entryId, cols.entryId).padEnd(cols.entryId) + truncate(e.eventId, cols.eventId).padEnd(cols.eventId) + truncate(e.kind, cols.kind).padEnd(cols.kind) + String(e.failureCount).padEnd(cols.failCount) + truncate(e.lastError, cols.lastError)
+        );
+      }
+    } else {
+      console.log(
+        "ENTRY ID".padEnd(cols.entryId) + "EVENT ID".padEnd(cols.eventId) + "KIND".padEnd(cols.kind) + "FAIL#".padEnd(cols.failCount) + "LAST ERROR"
+      );
+      for (const e of entries) {
+        console.log(
+          truncate(e.entryId, cols.entryId).padEnd(cols.entryId) + truncate(e.eventId, cols.eventId).padEnd(cols.eventId) + truncate(e.kind, cols.kind).padEnd(cols.kind) + String(e.failureCount).padEnd(cols.failCount) + truncate(e.lastError, cols.lastError)
+        );
+      }
+    }
+  }
+}
+
+// src/cli/commands/replayDeadLetter.ts
+async function findByEventId(redis, stream, eventId) {
+  let cursor = "-";
+  while (true) {
+    const batch = await redis.xrange(stream, cursor, "+", 100);
+    if (batch.length === 0) return null;
+    for (const msg of batch) {
+      const dataStr = msg.fields["data"];
+      if (dataStr) {
+        try {
+          const parsed = JSON.parse(dataStr);
+          if (parsed["event_id"] === eventId) return msg;
+        } catch {
+        }
+      }
+    }
+    const last = batch[batch.length - 1];
+    if (!last || batch.length < 100) return null;
+    cursor = "(" + last.id;
+  }
+}
+async function replaySingle(redis, liveStream, deadStream, subId, msg, dryRun) {
+  const dataStr = msg.fields["data"];
+  if (!dataStr) return null;
+  let eventId = "";
+  try {
+    const parsed = JSON.parse(dataStr);
+    eventId = typeof parsed["event_id"] === "string" ? parsed["event_id"] : "";
+  } catch {
+  }
+  if (dryRun) {
+    console.log(`[dry-run] Would replay event ${eventId || msg.id} \u2192 live stream, delete from dead-letter.`);
+    return null;
+  }
+  const newId = await redis.xadd(liveStream, { data: dataStr });
+  await redis.xdel(deadStream, msg.id);
+  if (eventId) {
+    await redis.hdel(RedisKeys.subFailuresHash(subId), eventId);
+  }
+  return newId;
+}
+async function replayDeadLetter(redis, chainId, subId, eventId, all, dryRun) {
+  const liveStream = RedisKeys.eventsStream(chainId);
+  const deadStream = RedisKeys.deadLetterStream(chainId, subId);
+  if (all) {
+    let cursor = "-";
+    let replayed = 0;
+    while (true) {
+      const batch = await redis.xrange(deadStream, cursor, "+", 100);
+      if (batch.length === 0) break;
+      for (const msg2 of batch) {
+        const newId2 = await replaySingle(redis, liveStream, deadStream, subId, msg2, dryRun);
+        if (newId2 !== null) replayed++;
+      }
+      if (dryRun) {
+        replayed = batch.length;
+        break;
+      }
+      if (batch.length < 100) break;
+      cursor = "-";
+      if (replayed > 0) break;
+    }
+    if (dryRun) {
+      console.log(`[dry-run] Would replay ${replayed} events from dead-letter stream for ${subId}.`);
+    } else {
+      console.log(`Replayed ${replayed} events, removed ${replayed} from dead-letter.`);
+    }
+    return;
+  }
+  if (!eventId) throw new Error("--event-id is required unless --all is specified");
+  const msg = await findByEventId(redis, deadStream, eventId);
+  if (!msg) {
+    console.error(`Event not found in dead-letter stream for subscription ${subId}.`);
+    process.exit(1);
+  }
+  const newId = await replaySingle(redis, liveStream, deadStream, subId, msg, dryRun);
+  if (newId !== null) {
+    console.log(`Replayed event ${eventId} \u2192 new entry id ${newId}. Removed from dead-letter.`);
+  }
+}
+
+// src/cli/index.ts
+var program = new Command();
+program.name("parser").description("@coopenomics/parser \u2014 universal EOSIO/Antelope blockchain indexer").version("0.1.0");
+program.command("validate <config-file>").description("Validate config file without starting the parser").option("--json", "Output result as JSON").action((configFile, opts) => {
+  try {
+    const config = fromConfigFile(configFile);
+    const redacted = {
+      ship: { url: redactUrl(config.ship.url) },
+      chain: config.chain ? { url: config.chain.url ? redactUrl(config.chain.url) : void 0, id: config.chain.id } : void 0,
+      redis: { url: redactUrl(config.redis.url) }
+    };
+    if (opts.json) {
+      console.log(JSON.stringify({ valid: true, config: redacted }));
+    } else {
+      console.log("\u2713 Config valid");
+      console.log(JSON.stringify(redacted, null, 2));
+    }
+    process.exit(0);
+  } catch (err) {
+    if (err instanceof ConfigSecurityError) {
+      if (opts.json) {
+        console.error(JSON.stringify({ valid: false, errors: [`SECURITY: ${err.message}`] }));
+      } else {
+        console.error(`SECURITY: secrets must not be hardcoded`);
+        console.error(err.message);
+      }
+      process.exit(2);
+    }
+    if (err instanceof ConfigValidationError) {
+      const message = err.message;
+      if (opts.json) {
+        console.error(JSON.stringify({ valid: false, errors: [message] }));
+      } else {
+        console.error("\u2717 Config invalid:");
+        console.error(message);
+      }
+      process.exit(1);
+    }
+    if (opts.json) {
+      console.error(JSON.stringify({ valid: false, errors: [String(err)] }));
+    } else {
+      console.error("\u2717 Config invalid:");
+      console.error(String(err));
+    }
+    process.exit(1);
+  }
+});
+program.command("list-subscriptions").description("List registered subscriptions with consumer group stats").requiredOption("--config <file>", "Config file path").option("--chain-id <id>", "Override chain ID from config").option("--json", "Output as JSON").action(async (opts) => {
+  let redis = null;
+  try {
+    const config = fromConfigFile(opts.config);
+    const chainId = opts.chainId ?? config.chain?.id ?? "default";
+    redis = new IoRedisStore(config.redis);
+    await redis.connect();
+    await listSubscriptions(redis, chainId, opts.json ?? false);
+    process.exit(0);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  } finally {
+    await redis?.quit();
+  }
+});
+program.command("reset-subscription").description("Rewind a subscription consumer group to a specific block").requiredOption("--config <file>", "Config file path").requiredOption("--sub-id <id>", "Subscription ID to reset").requiredOption("--to-block <n>", 'Target block number (0 or "latest" = skip to end)').option("--chain-id <id>", "Override chain ID from config").option("--dry-run", "Show what would be done without executing").action(async (opts) => {
+  let redis = null;
+  try {
+    const config = fromConfigFile(opts.config);
+    const chainId = opts.chainId ?? config.chain?.id ?? "default";
+    redis = new IoRedisStore(config.redis);
+    await redis.connect();
+    await resetSubscription(redis, chainId, opts.subId, opts.toBlock, opts.dryRun ?? false);
+    process.exit(0);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  } finally {
+    await redis?.quit();
+  }
+});
+program.command("abi-prune").description("Prune old ABI versions from a contract ZSET").requiredOption("--config <file>", "Config file path").option("--contract <name>", "Contract name to prune").option("--older-than <block>", "Remove versions older than this block number").option("--dry-run", "Show what would be done without executing").option("--all-contracts", "Apply prune to all contracts with ABI history").action(async (opts) => {
+  let redis = null;
+  try {
+    const config = fromConfigFile(opts.config);
+    redis = new IoRedisStore(config.redis);
+    await redis.connect();
+    const olderThan = opts.olderThan !== void 0 ? Number(opts.olderThan) : 0;
+    if (isNaN(olderThan)) throw new Error(`Invalid --older-than value: ${opts.olderThan}`);
+    await abiPrune(redis, opts.contract ?? null, olderThan, opts.dryRun ?? false, opts.allContracts ?? false);
+    process.exit(0);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  } finally {
+    await redis?.quit();
+  }
+});
+program.command("list-dead-letters").description("Inspect dead-letter stream for a subscription").requiredOption("--config <file>", "Config file path").option("--sub-id <id>", "Subscription ID to inspect").option("--chain-id <id>", "Override chain ID from config").option("--all", "Inspect all dead-letter streams").option("--json", "Output as JSON").option("--limit <n>", "Max entries to show", "100").option("--from <entryId>", "Start from this entry ID (pagination)", "-").action(async (opts) => {
+  let redis = null;
+  try {
+    const config = fromConfigFile(opts.config);
+    const chainId = opts.chainId ?? config.chain?.id ?? "default";
+    redis = new IoRedisStore(config.redis);
+    await redis.connect();
+    await listDeadLetters(
+      redis,
+      chainId,
+      opts.subId ?? null,
+      opts.json ?? false,
+      Number(opts.limit ?? 100),
+      opts.from ?? "-",
+      opts.all ?? false
+    );
+    process.exit(0);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  } finally {
+    await redis?.quit();
+  }
+});
+program.command("replay-dead-letter").description("Replay a dead-letter event back into the live stream").requiredOption("--config <file>", "Config file path").requiredOption("--sub-id <id>", "Subscription ID").option("--event-id <id>", "Event ID to replay").option("--all", "Replay all dead-letter events for the subscription").option("--chain-id <id>", "Override chain ID from config").option("--dry-run", "Show what would be done without executing").action(async (opts) => {
+  let redis = null;
+  try {
+    const config = fromConfigFile(opts.config);
+    const chainId = opts.chainId ?? config.chain?.id ?? "default";
+    redis = new IoRedisStore(config.redis);
+    await redis.connect();
+    await replayDeadLetter(
+      redis,
+      chainId,
+      opts.subId,
+      opts.eventId ?? null,
+      opts.all ?? false,
+      opts.dryRun ?? false
+    );
+    process.exit(0);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  } finally {
+    await redis?.quit();
+  }
+});
+function redactUrl(url) {
+  try {
+    const u = new URL(url);
+    if (u.password) u.password = "***";
+    return u.toString();
+  } catch {
+    return url;
+  }
+}
+program.parse(process.argv);
+//# sourceMappingURL=index.js.map