chore(miner): migrate batch 4.8 highest-fan-in lib modules to TypeScript

Convert governor-ledger, event-ledger, portfolio-queue, and cli-error from
hand-maintained .js + .d.ts to real TypeScript, compiled in place via the
package's existing tsc pipeline (#7290 Phase 4, batch 4.8 — the final, highest
fan-in batch). Public API is preserved exactly and the compiled .js output is
behavior-identical; only type annotations, identity row-cast helpers, and tsc
formatting differ. Adds tests for the branches the migration newly tracks so all
four files are at 100% line + branch + function coverage.

Closes #7316

Author: xfodev

packages/loopover-miner/lib/cli-error.d.ts

@@ -1,3 +1,7 @@
-export function reportCliFailure(wantsJson: boolean, message: string, exitCode?: number): number;
-export function argsWantJson(args: readonly string[]): boolean;
-export function describeCliError(error: unknown): string;
+/** Shared CLI failure output (#4836): when `--json` is set, emit a parseable `{ ok: false, error }` object on
+ *  stdout (matching each command's success-path JSON stream); otherwise log plain text to stderr. */
+export declare function reportCliFailure(wantsJson: boolean, message: string, exitCode?: number): number;
+/** True when argv includes `--json` (used on parse-error paths before a full parse result exists). */
+export declare function argsWantJson(args: readonly string[]): boolean;
+/** Normalize a thrown value to a safe error string for CLI output. */
+export declare function describeCliError(error: unknown): string;

packages/loopover-miner/lib/cli-error.js

@@ -0,0 +1,21 @@
+/** Shared CLI failure output (#4836): when `--json` is set, emit a parseable `{ ok: false, error }` object on
+ *  stdout (matching each command's success-path JSON stream); otherwise log plain text to stderr. */
+
+export function reportCliFailure(wantsJson: boolean, message: string, exitCode = 2): number {
+  if (wantsJson) {
+    console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+  } else {
+    console.error(message);
+  }
+  return exitCode;
+}
+
+/** True when argv includes `--json` (used on parse-error paths before a full parse result exists). */
+export function argsWantJson(args: readonly string[]): boolean {
+  return args.includes("--json");
+}
+
+/** Normalize a thrown value to a safe error string for CLI output. */
+export function describeCliError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

packages/loopover-miner/lib/cli-error.ts

@@ -1,37 +1,35 @@
 export type LedgerEntry = {
-  id: number;
-  seq: number;
-  type: string;
-  repoFullName: string | null;
-  payload: Record<string, unknown>;
-  createdAt: string;
+    id: number;
+    seq: number;
+    type: string;
+    repoFullName: string | null;
+    payload: Record<string, unknown>;
+    createdAt: string;
 };
-
 export type AppendEventInput = {
-  type: string;
-  repoFullName?: string;
-  payload: Record<string, unknown>;
+    type: string;
+    repoFullName?: string;
+    payload: Record<string, unknown>;
 };
-
 export type ReadEventsFilter = {
-  repoFullName?: string | null;
-  since?: number | null;
+    repoFullName?: string | null;
+    since?: number | null;
 };
-
 export type EventLedger = {
-  dbPath: string;
-  appendEvent(event: AppendEventInput): LedgerEntry;
-  readEvents(filter?: ReadEventsFilter): LedgerEntry[];
-  purgeByRepo(repoFullName: string): number;
-  close(): void;
+    dbPath: string;
+    appendEvent(event: AppendEventInput): LedgerEntry;
+    readEvents(filter?: ReadEventsFilter): LedgerEntry[];
+    purgeByRepo(repoFullName: string): number;
+    close(): void;
 };
-
-export function resolveEventLedgerDbPath(env?: Record<string, string | undefined>): string;
-
-export function initEventLedger(dbPath?: string): EventLedger;
-
-export function appendEvent(event: AppendEventInput): LedgerEntry;
-
-export function readEvents(filter?: ReadEventsFilter): LedgerEntry[];
-
-export function closeDefaultEventLedger(): void;
+export declare function resolveEventLedgerDbPath(env?: Record<string, string | undefined>): string;
+/**
+ * Opens the local append-only event ledger, creating the table on first use. `seq` is a monotonically increasing
+ * counter maintained by this module (next = current MAX(seq) + 1) rather than relying on `AUTOINCREMENT`'s
+ * reuse-after-vacuum behavior, so consumers get a stable ordering guarantee. Rows read back in `seq ASC` order.
+ * (#2290)
+ */
+export declare function initEventLedger(dbPath?: string): EventLedger;
+export declare function appendEvent(event: AppendEventInput): LedgerEntry;
+export declare function readEvents(filter?: ReadEventsFilter): LedgerEntry[];
+export declare function closeDefaultEventLedger(): void;