@gzeoneth/gov-tracker 0.2.1 → 0.3.0

package/dist/types/tracking.d.ts

@@ -3,9 +3,9 @@
  */
 import { Chain, ChainId, StageType } from "./core";
 import { TrackedStage } from "./stages";
-import { CallScheduledData } from "./timelock";
+import { CallScheduledData, TimelockLink } from "./timelock";
 import { ProposalType, ProposalData, ProposalState } from "./governor";
-import { TimelockState, TimelockLink } from "./timelock";
+import { ElectionProposalStatus, SerializableNomineeDetails, SerializableMemberDetails } from "./election";
 export interface PrepareOptions {
     salt?: string;
     predecessor?: string;
@@ -61,10 +61,17 @@ export interface DiscoveryTrackingInput {
     type: "discovery";
     id: "watermarks";
 }
+/**
+ * Input for tracking a Security Council election
+ */
+export interface ElectionTrackingInput {
+    type: "election";
+    electionIndex: number;
+}
 /**
  * Union type for all tracking entry points
  */
-export type TrackingInput = GovernorTrackingInput | TimelockTrackingInput | DiscoveryTrackingInput;
+export type TrackingInput = GovernorTrackingInput | TimelockTrackingInput | DiscoveryTrackingInput | ElectionTrackingInput;
 /**
  * Hints for the next stage in the pipeline
  */
@@ -90,6 +97,8 @@ export interface StageTrackResult {
 export type DiscoveryKey = "constitutionalGovernor" | "nonConstitutionalGovernor" | "electionNomineeGovernor" | "electionMemberGovernor" | "l2ConstitutionalTimelock" | "l2NonConstitutionalTimelock";
 /** Discovery watermarks for incremental block scanning */
 export type DiscoveryWatermarks = Partial<Record<DiscoveryKey, number>>;
+/** Block hashes for watermark reorg detection */
+export type WatermarkHashes = Partial<Record<DiscoveryKey, string>>;
 /** Discovery targets configuration */
 export type DiscoveryTargets = Partial<Record<DiscoveryKey, boolean>>;
 /**
@@ -108,10 +117,30 @@ export interface TrackingCheckpoint {
     cachedData: {
         completedStages?: TrackedStage[];
         discoveryWatermarks?: DiscoveryWatermarks;
+        /** Block hashes for reorg detection */
+        watermarkHashes?: WatermarkHashes;
+        /** Election status for election checkpoints */
+        electionStatus?: ElectionProposalStatus;
+        /** Nominee election details for completed elections */
+        nomineeDetails?: SerializableNomineeDetails;
+        /** Member election details for completed elections */
+        memberDetails?: SerializableMemberDetails;
     };
     metadata?: {
         errorCount: number;
         lastTrackedAt: number;
+        /**
+         * Reference to the parent checkpoint that created this timelock operation.
+         * Used for deduplication when tracking results spawn child timelock operations.
+         *
+         * Examples:
+         * - Election executes → schedules to L2 timelock → sourceCheckpoint = "election:5"
+         * - Proposal queued → schedules to L2 timelock → sourceCheckpoint = "tx:0x..."
+         * - L2 timelock executed → schedules to L1 → child already tracked in stages, no need for separate key
+         *
+         * @see linkCheckpointToChild
+         */
+        sourceCheckpoint?: string;
     };
 }
 /**
@@ -146,9 +175,10 @@ export interface TrackingResult {
     isComplete: boolean;
     proposalType?: ProposalType;
     proposalData?: ProposalData;
-    timelockState?: TimelockState;
     timelockLink?: TimelockLink;
     currentState?: ProposalState;
     isElection?: boolean;
+    /** Election status for election proposals - includes full lifecycle tracking */
+    electionStatus?: ElectionProposalStatus;
 }
 //# sourceMappingURL=tracking.d.ts.map

package/dist/types/tracking.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracking.d.ts","sourceRoot":"","sources":["../../src/types/tracking.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAIzD,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,6BAA6B,CAAC,EAAE,OAAO,CAAC;IACxC,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,mBAAmB,CAAA;CAAE,GAChD;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACvD;AAID;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,UAAU,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,UAAU,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,WAAW,CAAC;IAClB,EAAE,EAAE,YAAY,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,qBAAqB,GAAG,qBAAqB,GAAG,sBAAsB,CAAC;AAEnG;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,iBAAiB,EAAE,CAAC;IAC5D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,cAAc,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB,wBAAwB,GACxB,2BAA2B,GAC3B,yBAAyB,GACzB,wBAAwB,GACxB,0BAA0B,GAC1B,6BAA6B,CAAC;AAElC,0DAA0D;AAC1D,MAAM,MAAM,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;AAExE,sCAAsC;AACtC,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,CAAC,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,aAAa,CAAC;IACrB,kBAAkB,EAAE,SAAS,GAAG,IAAI,CAAC;IACrC,kBAAkB,EAAE;QAClB,EAAE,EAAE,MAAM,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IACF,UAAU,EAAE;QACV,eAAe,CAAC,EAAE,YAAY,EAAE,CAAC;QACjC,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;KAC3C,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,UAAU,EAAE,MAAM,CAAC;QACnB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,SAAS,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,SAAS,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,UAAU,EAAE,kBAAkB,CAAC;IAC/B,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB"}
+{"version":3,"file":"tracking.d.ts","sourceRoot":"","sources":["../../src/types/tracking.ts"],"names":[],"mappings":"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"}

package/dist/utils/block-cache.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Block-scoped cache for RPC results
+ *
+ * Caches results that are immutable at a specific block number.
+ * Does NOT cache results queried at "latest" (mutable).
+ */
+export interface BlockCacheOptions<T> {
+    /** Optional predicate to determine if result should be cached even without blockNumber */
+    isImmutable?: (value: T) => boolean;
+}
+/**
+ * A cache that stores values scoped by block number.
+ * Only caches when blockNumber is provided (immutable historical state),
+ * OR when the value passes the isImmutable predicate.
+ */
+export declare class BlockScopedCache<K, V> {
+    private cache;
+    private isImmutable?;
+    constructor(options?: BlockCacheOptions<V>);
+    private makeKey;
+    /**
+     * Get a cached value.
+     * @param key - The cache key
+     * @param blockNumber - If provided, looks up block-scoped entry. If not, looks up "latest" entry.
+     * @param options.skipCache - If true, always returns undefined (forces fresh fetch)
+     */
+    get(key: K, blockNumber?: number, options?: {
+        skipCache?: boolean;
+    }): V | undefined;
+    /**
+     * Set a cached value.
+     * @param key - The cache key
+     * @param value - The value to cache
+     * @param blockNumber - If provided, caches as immutable block-scoped entry
+     */
+    set(key: K, value: V, blockNumber?: number): void;
+    /**
+     * Check if a value exists in cache.
+     */
+    has(key: K, blockNumber?: number): boolean;
+    /**
+     * Clear all cached entries.
+     */
+    clear(): void;
+    /**
+     * Get the number of cached entries.
+     */
+    get size(): number;
+}
+//# sourceMappingURL=block-cache.d.ts.map

package/dist/utils/block-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-cache.d.ts","sourceRoot":"","sources":["../../src/utils/block-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,0FAA0F;IAC1F,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;CACrC;AAED;;;;GAIG;AACH,qBAAa,gBAAgB,CAAC,CAAC,EAAE,CAAC;IAChC,OAAO,CAAC,KAAK,CAAwB;IACrC,OAAO,CAAC,WAAW,CAAC,CAAwB;gBAEhC,OAAO,GAAE,iBAAiB,CAAC,CAAC,CAAM;IAI9C,OAAO,CAAC,OAAO;IAKf;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,CAAC,GAAG,SAAS;IAgBnF;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI;IAWjD;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO;IAI1C;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/utils/block-cache.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Block-scoped cache for RPC results
+ *
+ * Caches results that are immutable at a specific block number.
+ * Does NOT cache results queried at "latest" (mutable).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BlockScopedCache = void 0;
+/**
+ * A cache that stores values scoped by block number.
+ * Only caches when blockNumber is provided (immutable historical state),
+ * OR when the value passes the isImmutable predicate.
+ */
+class BlockScopedCache {
+    constructor(options = {}) {
+        this.cache = new Map();
+        this.isImmutable = options.isImmutable;
+    }
+    makeKey(key, blockNumber) {
+        const keyStr = typeof key === "string" ? key : JSON.stringify(key);
+        return blockNumber !== undefined ? `${keyStr}:${blockNumber}` : keyStr;
+    }
+    /**
+     * Get a cached value.
+     * @param key - The cache key
+     * @param blockNumber - If provided, looks up block-scoped entry. If not, looks up "latest" entry.
+     * @param options.skipCache - If true, always returns undefined (forces fresh fetch)
+     */
+    get(key, blockNumber, options) {
+        // Skip cache if requested
+        if (options?.skipCache) {
+            return undefined;
+        }
+        // When blockNumber is provided, only check block-scoped cache
+        if (blockNumber !== undefined) {
+            return this.cache.get(this.makeKey(key, blockNumber));
+        }
+        // When no blockNumber, check if we have an immutable "latest" entry
+        const latestKey = this.makeKey(key);
+        return this.cache.get(latestKey);
+    }
+    /**
+     * Set a cached value.
+     * @param key - The cache key
+     * @param value - The value to cache
+     * @param blockNumber - If provided, caches as immutable block-scoped entry
+     */
+    set(key, value, blockNumber) {
+        if (blockNumber !== undefined) {
+            // Block-scoped: always cache (immutable historical state)
+            this.cache.set(this.makeKey(key, blockNumber), value);
+        }
+        else if (this.isImmutable?.(value)) {
+            // No blockNumber but value is immutable: cache as "latest"
+            this.cache.set(this.makeKey(key), value);
+        }
+        // Otherwise: don't cache (mutable state queried at "latest")
+    }
+    /**
+     * Check if a value exists in cache.
+     */
+    has(key, blockNumber) {
+        return this.cache.has(this.makeKey(key, blockNumber));
+    }
+    /**
+     * Clear all cached entries.
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get the number of cached entries.
+     */
+    get size() {
+        return this.cache.size;
+    }
+}
+exports.BlockScopedCache = BlockScopedCache;
+//# sourceMappingURL=block-cache.js.map

package/dist/utils/block-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-cache.js","sourceRoot":"","sources":["../../src/utils/block-cache.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAOH;;;;GAIG;AACH,MAAa,gBAAgB;IAI3B,YAAY,UAAgC,EAAE;QAHtC,UAAK,GAAG,IAAI,GAAG,EAAa,CAAC;QAInC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IACzC,CAAC;IAEO,OAAO,CAAC,GAAM,EAAE,WAAoB;QAC1C,MAAM,MAAM,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACnE,OAAO,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,WAAW,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;IACzE,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAC,GAAM,EAAE,WAAoB,EAAE,OAAiC;QACjE,0BAA0B;QAC1B,IAAI,OAAO,EAAE,SAAS,EAAE,CAAC;YACvB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,8DAA8D;QAC9D,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC;QACxD,CAAC;QAED,oEAAoE;QACpE,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACnC,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAC,GAAM,EAAE,KAAQ,EAAE,WAAoB;QACxC,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,0DAA0D;YAC1D,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,WAAW,CAAC,EAAE,KAAK,CAAC,CAAC;QACxD,CAAC;aAAM,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;YACrC,2DAA2D;YAC3D,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;QAC3C,CAAC;QACD,6DAA6D;IAC/D,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,GAAM,EAAE,WAAoB;QAC9B,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC;IACxD,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;CACF;AAxED,4CAwEC"}

package/dist/utils/formatters.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Pure formatting utilities for display and logging
+ *
+ * These functions have no React/Ink dependencies and can be used
+ * by both the SDK and TUI.
+ */
+import type { TrackedStage, TrackingInput, DecodedCalldata } from "../types/index.js";
+import type { Chain } from "../types/index.js";
+/**
+ * Wrap text to fit within a given width, breaking at character boundaries
+ */
+export declare function wrapText(text: string, width: number): string[];
+/**
+ * Truncate text with ellipsis if it exceeds maxLen
+ */
+export declare function truncate(str: string, maxLen: number): string;
+/**
+ * Safely stringify a value, returning a fallback for complex objects
+ */
+export declare function safeStringify(value: unknown): string;
+/**
+ * Format an unknown value for display
+ */
+export declare function formatValue(value: unknown): string;
+/**
+ * Format a Unix timestamp to locale string
+ */
+export declare function formatDate(timestamp: number | null): string;
+/**
+ * Chain to chain ID mapping
+ */
+export declare const CHAIN_TO_CHAIN_ID: Record<Chain, number>;
+/**
+ * A formatted stage data item
+ */
+export interface StageDataItem {
+    label: string;
+    value: string;
+}
+/**
+ * Format stage data for display, prioritizing important fields
+ */
+export declare function formatStageData(stage: TrackedStage): StageDataItem[];
+/**
+ * Extract transaction hash from tracking input
+ */
+export declare function getTxHash(input: TrackingInput): string;
+/**
+ * Get display-friendly proposal or operation ID from tracking input
+ */
+export declare function getProposalIdDisplay(input: TrackingInput): string;
+/**
+ * A formatted line for calldata display
+ */
+export interface FormattedLine {
+    text: string;
+    indent: number;
+    foldable: boolean;
+    foldKey?: string;
+    foldedLineCount?: number;
+    isFoldedContent?: boolean;
+}
+/**
+ * Format decoded calldata into displayable lines
+ */
+export declare function formatDecodedCalldata(decoded: DecodedCalldata, indent?: number, keyPrefix?: string): FormattedLine[];
+/**
+ * Filter lines based on expanded fold keys
+ */
+export declare function filterVisibleLines(allLines: FormattedLine[], expandedKeys: Set<string>): FormattedLine[];
+/**
+ * Get all foldable keys from lines
+ */
+export declare function getAllFoldableKeys(lines: FormattedLine[]): string[];
+/**
+ * Toggle a fold key in the expanded set
+ */
+export declare function toggleFoldKey(expandedKeys: Set<string>, foldKey: string): Set<string>;
+/**
+ * Format duration in seconds to human-readable string
+ *
+ * Displays the two most significant time units (e.g., "2d 3h" or "5m 30s").
+ * Returns "now" for zero or negative values.
+ *
+ * @example
+ * formatDuration(90061) // => "1d 1h"
+ * formatDuration(3661)  // => "1h 1m"
+ * formatDuration(65)    // => "1m 5s"
+ */
+export declare function formatDuration(seconds: number): string;
+//# sourceMappingURL=formatters.d.ts.map

package/dist/utils/formatters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatters.d.ts","sourceRoot":"","sources":["../../src/utils/formatters.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,eAAe,EAEhB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAM/C;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAO9D;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAI5D;AAMD;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAMpD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAYlD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAG3D;AAMD;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAKnD,CAAC;AAoCF;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,aAAa,EAAE,CA6BpE;AAMD;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAUtD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAWjE;AAMD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAuDD;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,eAAe,EACxB,MAAM,SAAI,EACV,SAAS,SAAS,GACjB,aAAa,EAAE,CAoBjB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,aAAa,EAAE,EACzB,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,GACxB,aAAa,EAAE,CAKjB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,MAAM,EAAE,CAEnE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAQrF;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAgBtD"}

package/dist/utils/formatters.js

@@ -0,0 +1,327 @@
+"use strict";
+/**
+ * Pure formatting utilities for display and logging
+ *
+ * These functions have no React/Ink dependencies and can be used
+ * by both the SDK and TUI.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHAIN_TO_CHAIN_ID = void 0;
+exports.wrapText = wrapText;
+exports.truncate = truncate;
+exports.safeStringify = safeStringify;
+exports.formatValue = formatValue;
+exports.formatDate = formatDate;
+exports.formatStageData = formatStageData;
+exports.getTxHash = getTxHash;
+exports.getProposalIdDisplay = getProposalIdDisplay;
+exports.formatDecodedCalldata = formatDecodedCalldata;
+exports.filterVisibleLines = filterVisibleLines;
+exports.getAllFoldableKeys = getAllFoldableKeys;
+exports.toggleFoldKey = toggleFoldKey;
+exports.formatDuration = formatDuration;
+const constants_js_1 = require("../constants.js");
+// ============================================================================
+// Text Utilities
+// ============================================================================
+/**
+ * Wrap text to fit within a given width, breaking at character boundaries
+ */
+function wrapText(text, width) {
+    if (text.length <= width)
+        return [text];
+    const lines = [];
+    for (let i = 0; i < text.length; i += width) {
+        lines.push(text.slice(i, i + width));
+    }
+    return lines;
+}
+/**
+ * Truncate text with ellipsis if it exceeds maxLen
+ */
+function truncate(str, maxLen) {
+    if (maxLen <= 1)
+        return str.length > 0 ? "..." : "";
+    if (str.length <= maxLen)
+        return str;
+    return str.slice(0, maxLen - 1) + "...";
+}
+// ============================================================================
+// Value Formatting
+// ============================================================================
+/**
+ * Safely stringify a value, returning a fallback for complex objects
+ */
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return "[complex object]";
+    }
+}
+/**
+ * Format an unknown value for display
+ */
+function formatValue(value) {
+    if (value === null || value === undefined)
+        return "N/A";
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number")
+        return value.toString();
+    if (typeof value === "boolean")
+        return value ? "Yes" : "No";
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return "[]";
+        if (value.length <= 3)
+            return safeStringify(value);
+        return `[${value.length} items]`;
+    }
+    if (typeof value === "object")
+        return safeStringify(value);
+    return String(value);
+}
+/**
+ * Format a Unix timestamp to locale string
+ */
+function formatDate(timestamp) {
+    if (timestamp === null)
+        return "Unknown";
+    return new Date(timestamp).toLocaleString();
+}
+// ============================================================================
+// Stage Formatting
+// ============================================================================
+/**
+ * Chain to chain ID mapping
+ */
+exports.CHAIN_TO_CHAIN_ID = {
+    ethereum: constants_js_1.CHAIN_IDS.ETHEREUM,
+    arb1: constants_js_1.CHAIN_IDS.ARB_ONE,
+    nova: constants_js_1.CHAIN_IDS.NOVA,
+    unknown: constants_js_1.CHAIN_IDS.ETHEREUM,
+};
+/**
+ * Priority fields shown first in stage data
+ */
+const STAGE_PRIORITY_FIELDS = [
+    "proposalId",
+    "operationId",
+    "proposer",
+    "description",
+    "proposalState",
+    "forVotes",
+    "againstVotes",
+    "abstainVotes",
+    "quorum",
+    "quorumReached",
+    "timelockAddress",
+    "eta",
+    "state",
+    "messageCount",
+    "ticketCount",
+    "redeemedCount",
+];
+/**
+ * Fields to skip in stage data display
+ */
+const STAGE_SKIP_FIELDS = [
+    "targets",
+    "values",
+    "calldatas",
+    "signatures",
+    "callScheduledData",
+    "_rawBytesArray",
+];
+/**
+ * Format stage data for display, prioritizing important fields
+ */
+function formatStageData(stage) {
+    const items = [];
+    const data = stage.data;
+    if (!data)
+        return items;
+    for (const field of STAGE_PRIORITY_FIELDS) {
+        if (field in data && data[field] !== undefined) {
+            let value = formatValue(data[field]);
+            if (field === "description" && value.length > 100) {
+                value = value.slice(0, 100) + "...";
+            }
+            items.push({ label: field, value });
+        }
+    }
+    for (const [key, value] of Object.entries(data)) {
+        if (STAGE_PRIORITY_FIELDS.includes(key))
+            continue;
+        if (STAGE_SKIP_FIELDS.includes(key))
+            continue;
+        if (value === undefined || value === null)
+            continue;
+        let formattedValue = formatValue(value);
+        if (formattedValue.length > 80) {
+            formattedValue = formattedValue.slice(0, 80) + "...";
+        }
+        items.push({ label: key, value: formattedValue });
+    }
+    return items;
+}
+// ============================================================================
+// Tracking Input Helpers
+// ============================================================================
+/**
+ * Extract transaction hash from tracking input
+ */
+function getTxHash(input) {
+    switch (input.type) {
+        case "governor":
+            return input.creationTxHash;
+        case "timelock":
+            return input.scheduledTxHash;
+        case "discovery":
+        case "election":
+            return "";
+    }
+}
+/**
+ * Get display-friendly proposal or operation ID from tracking input
+ */
+function getProposalIdDisplay(input) {
+    switch (input.type) {
+        case "governor":
+            return input.proposalId;
+        case "timelock":
+            return input.operationId;
+        case "discovery":
+            return input.id;
+        case "election":
+            return `election-${input.electionIndex}`;
+    }
+}
+const CALLDATA_FOLD_THRESHOLD = 100;
+function formatCalldataParameter(param, indent, keyPrefix) {
+    const lines = [];
+    const foldKey = `${keyPrefix}-${param.name}`;
+    let value = param.displayValue;
+    if (param.addressLabel) {
+        value = `${param.displayValue} [${param.addressLabel}]`;
+    }
+    const isFoldable = value.length > CALLDATA_FOLD_THRESHOLD;
+    const wrappedLines = isFoldable ? wrapText(value, 80) : [value];
+    lines.push({
+        text: `${param.name} (${param.type}): ${wrappedLines[0]}`,
+        indent,
+        foldable: isFoldable,
+        foldKey: isFoldable ? foldKey : undefined,
+        foldedLineCount: isFoldable ? wrappedLines.length - 1 : undefined,
+    });
+    if (isFoldable && wrappedLines.length > 1) {
+        for (let i = 1; i < wrappedLines.length; i++) {
+            lines.push({
+                text: wrappedLines[i],
+                indent: indent + 1,
+                foldable: false,
+                isFoldedContent: true,
+                foldKey,
+            });
+        }
+    }
+    if (param.nested) {
+        lines.push({ text: "|- [NESTED]", indent: indent + 1, foldable: false });
+        lines.push(...formatDecodedCalldata(param.nested, indent + 2, `${foldKey}-nested`));
+    }
+    if (param.nestedArray && param.nestedArray.length > 0) {
+        param.nestedArray.forEach((nested, i) => {
+            lines.push({ text: `[${i}]:`, indent: indent + 1, foldable: false });
+            lines.push(...formatDecodedCalldata(nested, indent + 2, `${foldKey}-arr-${i}`));
+        });
+    }
+    return lines;
+}
+/**
+ * Format decoded calldata into displayable lines
+ */
+function formatDecodedCalldata(decoded, indent = 0, keyPrefix = "root") {
+    const lines = [];
+    let header;
+    if (decoded.isRetryable) {
+        header = `Retryable Ticket -> ${decoded.targetChain}`;
+    }
+    else if (decoded.signature) {
+        header = decoded.signature;
+    }
+    else {
+        header = `Unknown function (${decoded.selector})`;
+    }
+    lines.push({ text: header, indent, foldable: false });
+    if (decoded.parameters) {
+        decoded.parameters.forEach((param, i) => {
+            lines.push(...formatCalldataParameter(param, indent + 1, `${keyPrefix}-p${i}`));
+        });
+    }
+    return lines;
+}
+/**
+ * Filter lines based on expanded fold keys
+ */
+function filterVisibleLines(allLines, expandedKeys) {
+    return allLines.filter((line) => {
+        if (!line.isFoldedContent)
+            return true;
+        return line.foldKey && expandedKeys.has(line.foldKey);
+    });
+}
+/**
+ * Get all foldable keys from lines
+ */
+function getAllFoldableKeys(lines) {
+    return lines.filter((l) => l.foldable && l.foldKey).map((l) => l.foldKey);
+}
+/**
+ * Toggle a fold key in the expanded set
+ */
+function toggleFoldKey(expandedKeys, foldKey) {
+    const next = new Set(expandedKeys);
+    if (next.has(foldKey)) {
+        next.delete(foldKey);
+    }
+    else {
+        next.add(foldKey);
+    }
+    return next;
+}
+// ============================================================================
+// Duration Formatting
+// ============================================================================
+/**
+ * Format duration in seconds to human-readable string
+ *
+ * Displays the two most significant time units (e.g., "2d 3h" or "5m 30s").
+ * Returns "now" for zero or negative values.
+ *
+ * @example
+ * formatDuration(90061) // => "1d 1h"
+ * formatDuration(3661)  // => "1h 1m"
+ * formatDuration(65)    // => "1m 5s"
+ */
+function formatDuration(seconds) {
+    if (seconds <= 0)
+        return "now";
+    const totalSeconds = Math.floor(seconds);
+    const days = Math.floor(totalSeconds / 86400);
+    const hours = Math.floor((totalSeconds % 86400) / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const secs = totalSeconds % 60;
+    const parts = [];
+    if (days > 0)
+        parts.push(`${days}d`);
+    if (hours > 0 && parts.length < 2)
+        parts.push(`${hours}h`);
+    if (minutes > 0 && parts.length < 2)
+        parts.push(`${minutes}m`);
+    if (secs > 0 && parts.length < 2)
+        parts.push(`${secs}s`);
+    return parts.join(" ") || "0s";
+}
+//# sourceMappingURL=formatters.js.map