lovewebconnection 0.0.0-stage → 0.2.1

package/dist/metadata-cache.d.ts

@@ -0,0 +1,72 @@
+import { type Address } from "viem";
+/** The immutable parts of an ERC-20's identity, read once and reused. */
+export interface TokenMetadata {
+    symbol: string;
+    decimals: number;
+}
+/** Cached metadata plus when it was last verified; null for legacy entries. */
+export interface CachedTokenMetadata extends TokenMetadata {
+    cachedAt: number | null;
+}
+/** A cached entry paired with its checksummed token address. */
+export interface ListedTokenMetadata extends CachedTokenMetadata {
+    address: Address;
+}
+export interface MetadataCacheOptions {
+    /** Only entries for this chain are returned. */
+    chainId: number;
+    /** File to load from and save to; ignored when `persist` is false. */
+    path?: string;
+    /** False keeps everything in memory and never touches the disk. */
+    persist?: boolean;
+    /** Clock used for entry timestamps; injectable for tests. */
+    now?: () => number;
+}
+export declare const DEFAULT_CACHE_PATH = ".lwc-cache/token-metadata.json";
+export type CacheAgeParse = {
+    ok: true;
+    ms: number;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Parse cache-age flags (`--max-cache-age`, `--stale-after`): a positive whole
+ * number with a unit, for example `30m`, `12h`, `7d`, or `2w`. A bare number is
+ * rejected so seconds and milliseconds are never guessed.
+ */
+export declare function parseCacheAge(raw: string, flag?: string): CacheAgeParse;
+/** Flag value wins, then LWC_CACHE_FILE, then the project-local default. */
+export declare function resolveCachePath(flagPath?: string | null, env?: NodeJS.ProcessEnv): string;
+/**
+ * `decimals` and `symbol` are cached per chain and reused across runs and across
+ * owners within a scan. Entries record when they were last verified so a stale
+ * symbol can be spotted and refreshed. Only clean metadata is stored: a token
+ * whose symbol or decimals did not decode is left out, so a malformed contract
+ * is re-examined rather than remembered as broken.
+ */
+export declare class MetadataCache {
+    private readonly chainId;
+    private readonly path;
+    private readonly persist;
+    private readonly now;
+    private readonly entries;
+    private dirty;
+    constructor(options: MetadataCacheOptions);
+    get(token: string): TokenMetadata | null;
+    /** Every entry for this cache's chain, oldest first (undated entries first). */
+    list(): ListedTokenMetadata[];
+    /** How old this entry is in milliseconds; null when it has no timestamp. */
+    ageMs(token: string, now?: number): number | null;
+    set(token: string, metadata: TokenMetadata): void;
+    /**
+     * Drop every entry older than `maxAgeMs`, plus undated entries whose age
+     * cannot be checked. Returns how many entries were removed.
+     */
+    invalidateStale(maxAgeMs: number, now?: number): number;
+    /** Drop an entry so the next read re-fetches it; true when one was removed. */
+    invalidate(token: string): boolean;
+    /** Persist changes; returns a warning message instead of throwing on failure. */
+    save(): string | null;
+    private load;
+}

package/dist/metadata-cache.js

@@ -0,0 +1,197 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { getAddress, isAddress } from "viem";
+export const DEFAULT_CACHE_PATH = ".lwc-cache/token-metadata.json";
+/**
+ * Parse cache-age flags (`--max-cache-age`, `--stale-after`): a positive whole
+ * number with a unit, for example `30m`, `12h`, `7d`, or `2w`. A bare number is
+ * rejected so seconds and milliseconds are never guessed.
+ */
+export function parseCacheAge(raw, flag = "--max-cache-age") {
+    const match = /^(\d+)([smhdw])$/.exec(raw.trim());
+    if (!match) {
+        return {
+            ok: false,
+            message: `${flag} must look like 30m, 12h, 7d, or 2w, got "${raw}".`,
+        };
+    }
+    const value = Number(match[1]);
+    const unit = match[2];
+    const factor = unit === "s"
+        ? 1_000
+        : unit === "m"
+            ? 60_000
+            : unit === "h"
+                ? 3_600_000
+                : unit === "d"
+                    ? 86_400_000
+                    : 604_800_000;
+    const ms = value * factor;
+    if (ms <= 0 || !Number.isSafeInteger(ms)) {
+        return { ok: false, message: `${flag} must be a positive duration, got "${raw}".` };
+    }
+    return { ok: true, ms };
+}
+/** Flag value wins, then LWC_CACHE_FILE, then the project-local default. */
+export function resolveCachePath(flagPath = null, env = process.env) {
+    const value = flagPath ?? env.LWC_CACHE_FILE;
+    return value && value.trim().length > 0 ? value : DEFAULT_CACHE_PATH;
+}
+function usableEntry(value) {
+    const entry = value;
+    const symbol = typeof entry?.symbol === "string" ? entry.symbol.trim() : "";
+    const decimals = entry?.decimals;
+    if (!symbol || typeof decimals !== "number")
+        return null;
+    if (!Number.isInteger(decimals) || decimals < 0 || decimals > 36)
+        return null;
+    const cachedAt = typeof entry?.cachedAt === "number" && Number.isFinite(entry.cachedAt) && entry.cachedAt >= 0
+        ? entry.cachedAt
+        : null;
+    return { symbol, decimals, cachedAt };
+}
+/**
+ * `decimals` and `symbol` are cached per chain and reused across runs and across
+ * owners within a scan. Entries record when they were last verified so a stale
+ * symbol can be spotted and refreshed. Only clean metadata is stored: a token
+ * whose symbol or decimals did not decode is left out, so a malformed contract
+ * is re-examined rather than remembered as broken.
+ */
+export class MetadataCache {
+    chainId;
+    path;
+    persist;
+    now;
+    entries = new Map();
+    dirty = false;
+    constructor(options) {
+        this.chainId = options.chainId;
+        this.path = options.path ?? DEFAULT_CACHE_PATH;
+        this.persist = options.persist ?? true;
+        this.now = options.now ?? (() => Date.now());
+        if (this.persist)
+            this.load();
+    }
+    get(token) {
+        const entry = this.entries.get(String(this.chainId))?.get(token.toLowerCase());
+        return entry ? { symbol: entry.symbol, decimals: entry.decimals } : null;
+    }
+    /** Every entry for this cache's chain, oldest first (undated entries first). */
+    list() {
+        const scoped = this.entries.get(String(this.chainId));
+        if (!scoped)
+            return [];
+        return [...scoped.entries()]
+            .map(([address, entry]) => ({ address: getAddress(address), ...entry }))
+            .sort((a, b) => (a.cachedAt ?? 0) - (b.cachedAt ?? 0) || a.address.localeCompare(b.address));
+    }
+    /** How old this entry is in milliseconds; null when it has no timestamp. */
+    ageMs(token, now = Date.now()) {
+        const entry = this.entries.get(String(this.chainId))?.get(token.toLowerCase());
+        if (!entry || entry.cachedAt === null)
+            return null;
+        return Math.max(0, now - entry.cachedAt);
+    }
+    set(token, metadata) {
+        const usable = usableEntry({ ...metadata, cachedAt: this.now() });
+        if (!usable || !isAddress(token))
+            return;
+        const chain = String(this.chainId);
+        let scoped = this.entries.get(chain);
+        if (!scoped) {
+            scoped = new Map();
+            this.entries.set(chain, scoped);
+        }
+        const key = token.toLowerCase();
+        const existing = scoped.get(key);
+        if (existing && existing.symbol === usable.symbol && existing.decimals === usable.decimals) {
+            return;
+        }
+        scoped.set(key, usable);
+        this.dirty = true;
+    }
+    /**
+     * Drop every entry older than `maxAgeMs`, plus undated entries whose age
+     * cannot be checked. Returns how many entries were removed.
+     */
+    invalidateStale(maxAgeMs, now = Date.now()) {
+        const scoped = this.entries.get(String(this.chainId));
+        if (!scoped)
+            return 0;
+        let removed = 0;
+        for (const [address, entry] of scoped) {
+            if (entry.cachedAt === null || now - entry.cachedAt > maxAgeMs) {
+                scoped.delete(address);
+                removed += 1;
+            }
+        }
+        if (removed > 0)
+            this.dirty = true;
+        return removed;
+    }
+    /** Drop an entry so the next read re-fetches it; true when one was removed. */
+    invalidate(token) {
+        const scoped = this.entries.get(String(this.chainId));
+        if (!scoped?.delete(token.toLowerCase()))
+            return false;
+        this.dirty = true;
+        return true;
+    }
+    /** Persist changes; returns a warning message instead of throwing on failure. */
+    save() {
+        if (!this.persist || !this.dirty)
+            return null;
+        try {
+            const chains = {};
+            for (const [chain, scoped] of this.entries) {
+                const record = {};
+                for (const [address, metadata] of scoped)
+                    record[address] = metadata;
+                chains[chain] = record;
+            }
+            const payload = { version: 2, chains };
+            mkdirSync(dirname(this.path), { recursive: true });
+            const temporary = `${this.path}.tmp`;
+            writeFileSync(temporary, `${JSON.stringify(payload, null, 2)}\n`);
+            renameSync(temporary, this.path);
+            this.dirty = false;
+            return null;
+        }
+        catch (error) {
+            return error instanceof Error ? error.message : String(error);
+        }
+    }
+    load() {
+        let raw;
+        try {
+            raw = readFileSync(this.path, "utf8");
+        }
+        catch {
+            return; // No cache yet is the normal first-run case.
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return; // A damaged cache is worth ignoring, never worth failing a read.
+        }
+        const chains = parsed?.chains;
+        if (!chains || typeof chains !== "object")
+            return;
+        for (const [chain, record] of Object.entries(chains)) {
+            if (!/^\d+$/.test(chain) || !record || typeof record !== "object")
+                continue;
+            const scoped = new Map();
+            for (const [address, value] of Object.entries(record)) {
+                if (!isAddress(address))
+                    continue;
+                const metadata = usableEntry(value);
+                if (metadata)
+                    scoped.set(address.toLowerCase(), metadata);
+            }
+            if (scoped.size > 0)
+                this.entries.set(chain, scoped);
+        }
+    }
+}

package/dist/metrics.d.ts

@@ -0,0 +1,64 @@
+export interface LatencyStats {
+    count: number;
+    p50: number;
+    p95: number;
+    min: number;
+    max: number;
+    mean: number;
+}
+export interface BlockTimeStats {
+    count: number;
+    medianSeconds: number;
+    minSeconds: number;
+    maxSeconds: number;
+    meanSeconds: number;
+}
+export interface WatchMetrics {
+    samples: number;
+    windowSize: number;
+    latency: LatencyStats;
+    blockTime: BlockTimeStats;
+    windowFailures: number;
+    windowPolls: number;
+    /** Fraction of polls in the window that failed, 0..1. */
+    errorRate: number;
+}
+export interface MetricsState {
+    windowSize: number;
+    latencies: number[];
+    blockTimes: number[];
+    outcomes: boolean[];
+    samples: number;
+    errors: number;
+    /** Untrimmed history for session totals; absent on window-only states. */
+    sessionLatencies?: number[];
+    sessionBlockTimes?: number[];
+}
+/** Whole-run totals, as opposed to the rolling `WatchMetrics` window. */
+export interface SessionMetrics {
+    /** Successful polls in the run. */
+    samples: number;
+    /** Failed polls in the run. */
+    failures: number;
+    /** Successful plus failed polls. */
+    polls: number;
+    errorRate: number;
+    latency: LatencyStats;
+    blockTime: BlockTimeStats;
+}
+export declare const DEFAULT_METRICS_WINDOW = 20;
+export declare function createMetricsState(windowSize?: number): MetricsState;
+export declare function recordLatency(state: MetricsState, latencyMs: number): MetricsState;
+export declare function recordFailure(state: MetricsState): MetricsState;
+export declare function recordBlockTime(state: MetricsState, seconds: number): MetricsState;
+/** Nearest-rank percentile over an already sorted array. */
+export declare function percentile(sorted: number[], p: number): number;
+export declare function computeMetrics(state: MetricsState): WatchMetrics;
+/** Totals over the whole run, independent of the rolling window. */
+export declare function computeSessionMetrics(state: MetricsState): SessionMetrics;
+export declare function formatSeconds(seconds: number): string;
+/**
+ * One-line metrics report: the rolling window, plus whole-session totals when
+ * they are supplied, so recent health and the full run appear together.
+ */
+export declare function formatMetrics(metrics: WatchMetrics, session?: SessionMetrics): string;

package/dist/metrics.js

@@ -0,0 +1,138 @@
+export const DEFAULT_METRICS_WINDOW = 20;
+function emptyLatency() {
+    return { count: 0, p50: 0, p95: 0, min: 0, max: 0, mean: 0 };
+}
+function emptyBlockTime() {
+    return { count: 0, medianSeconds: 0, minSeconds: 0, maxSeconds: 0, meanSeconds: 0 };
+}
+export function createMetricsState(windowSize = DEFAULT_METRICS_WINDOW) {
+    return {
+        windowSize,
+        latencies: [],
+        blockTimes: [],
+        outcomes: [],
+        samples: 0,
+        errors: 0,
+        sessionLatencies: [],
+        sessionBlockTimes: [],
+    };
+}
+function trim(values, windowSize) {
+    return values.length > windowSize ? values.slice(-windowSize) : values;
+}
+export function recordLatency(state, latencyMs) {
+    const value = Math.max(0, Math.round(latencyMs));
+    return {
+        ...state,
+        latencies: trim([...state.latencies, value], state.windowSize),
+        outcomes: trim([...state.outcomes, true], state.windowSize),
+        sessionLatencies: [...(state.sessionLatencies ?? []), value],
+        samples: state.samples + 1,
+    };
+}
+export function recordFailure(state) {
+    return {
+        ...state,
+        outcomes: trim([...state.outcomes, false], state.windowSize),
+        errors: state.errors + 1,
+    };
+}
+export function recordBlockTime(state, seconds) {
+    const value = Math.max(0, seconds);
+    return {
+        ...state,
+        blockTimes: trim([...state.blockTimes, value], state.windowSize),
+        sessionBlockTimes: [...(state.sessionBlockTimes ?? []), value],
+    };
+}
+/** Nearest-rank percentile over an already sorted array. */
+export function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const rank = Math.ceil((p / 100) * sorted.length);
+    const index = Math.min(sorted.length - 1, Math.max(0, rank - 1));
+    return sorted[index] ?? 0;
+}
+function latencyStatsFrom(sorted) {
+    if (sorted.length === 0)
+        return emptyLatency();
+    return {
+        count: sorted.length,
+        p50: percentile(sorted, 50),
+        p95: percentile(sorted, 95),
+        min: sorted[0] ?? 0,
+        max: sorted[sorted.length - 1] ?? 0,
+        mean: Math.round(sorted.reduce((sum, value) => sum + value, 0) / sorted.length),
+    };
+}
+function blockTimeStatsFrom(sorted) {
+    if (sorted.length === 0)
+        return emptyBlockTime();
+    return {
+        count: sorted.length,
+        medianSeconds: percentile(sorted, 50),
+        minSeconds: sorted[0] ?? 0,
+        maxSeconds: sorted[sorted.length - 1] ?? 0,
+        meanSeconds: Number((sorted.reduce((sum, value) => sum + value, 0) / sorted.length).toFixed(3)),
+    };
+}
+export function computeMetrics(state) {
+    const latencies = [...state.latencies].sort((a, b) => a - b);
+    const blockTimes = [...state.blockTimes].sort((a, b) => a - b);
+    const windowPolls = state.outcomes.length;
+    const windowFailures = state.outcomes.filter((ok) => !ok).length;
+    return {
+        samples: state.samples,
+        windowSize: state.windowSize,
+        latency: latencyStatsFrom(latencies),
+        blockTime: blockTimeStatsFrom(blockTimes),
+        windowFailures,
+        windowPolls,
+        errorRate: windowPolls === 0 ? 0 : windowFailures / windowPolls,
+    };
+}
+/** Totals over the whole run, independent of the rolling window. */
+export function computeSessionMetrics(state) {
+    const latencies = [...(state.sessionLatencies ?? state.latencies)].sort((a, b) => a - b);
+    const blockTimes = [...(state.sessionBlockTimes ?? state.blockTimes)].sort((a, b) => a - b);
+    const polls = state.samples + state.errors;
+    return {
+        samples: state.samples,
+        failures: state.errors,
+        polls,
+        errorRate: polls === 0 ? 0 : state.errors / polls,
+        latency: latencyStatsFrom(latencies),
+        blockTime: blockTimeStatsFrom(blockTimes),
+    };
+}
+export function formatSeconds(seconds) {
+    if (seconds < 60)
+        return `${seconds.toFixed(1)}s`;
+    const minutes = Math.floor(seconds / 60);
+    const rest = Math.round(seconds % 60);
+    return `${minutes}m${rest.toString().padStart(2, "0")}s`;
+}
+/**
+ * One-line metrics report: the rolling window, plus whole-session totals when
+ * they are supplied, so recent health and the full run appear together.
+ */
+export function formatMetrics(metrics, session) {
+    const parts = [];
+    parts.push(metrics.latency.count > 0
+        ? `latency p50 ${metrics.latency.p50} ms, p95 ${metrics.latency.p95} ms, max ${metrics.latency.max} ms`
+        : "latency n/a");
+    parts.push(metrics.blockTime.count > 0
+        ? `block time median ${formatSeconds(metrics.blockTime.medianSeconds)}`
+        : "block time n/a");
+    parts.push(`errors ${metrics.windowFailures}/${metrics.windowPolls}`);
+    if (session) {
+        parts.push(session.latency.count > 0
+            ? `session latency p50 ${session.latency.p50} ms, p95 ${session.latency.p95} ms, max ${session.latency.max} ms`
+            : "session latency n/a");
+        parts.push(session.blockTime.count > 0
+            ? `session block time median ${formatSeconds(session.blockTime.medianSeconds)}`
+            : "session block time n/a");
+        parts.push(`session errors ${session.failures}/${session.polls}`);
+    }
+    return parts.join(" | ");
+}

package/dist/plot.d.ts

@@ -0,0 +1,60 @@
+export declare class PlotArgError extends Error {
+    constructor(message: string);
+}
+export interface PlotArgs {
+    /** History CSV written by `history --csv`, in long or `--wide` format. */
+    path: string;
+    /** Sparkline width in characters. */
+    width: number;
+}
+export interface PlotSample {
+    session: string;
+    /** Epoch milliseconds of the portfolio sample. */
+    at: number;
+    /** USD total of the priced holdings. */
+    total: number;
+}
+export interface PlotReport {
+    path: string;
+    width: number;
+    samples: PlotSample[];
+    /** Sessions that contributed samples, in time order. */
+    sessions: string[];
+    /** Samples whose holdings were all unpriced. */
+    skippedSamples: number;
+    firstAt: number | null;
+    lastAt: number | null;
+    first: number | null;
+    last: number | null;
+    min: number | null;
+    max: number | null;
+    change: number | null;
+    changePercent: number | null;
+    /** Sparkline of the totals, one character per sample or bucket. */
+    chart: string;
+}
+export declare const DEFAULT_PLOT_WIDTH = 48;
+export declare function parsePlotArgs(argv: string[]): PlotArgs;
+export declare function readHistoryCsv(path: string): string;
+/**
+ * Minimal RFC 4180 reader: quoted cells may hold commas, newlines, and doubled
+ * quotes, which is exactly what the history CSV writes for labels and flags.
+ */
+export declare function parseCsv(text: string): string[][];
+/**
+ * Turn a history CSV into one point per portfolio sample. The long format
+ * repeats `usd_total` on every asset row of a sample, so rows are grouped by
+ * session and timestamp; when `usd_total` is empty, that sample's row-level
+ * `usd` values are summed instead so a partly priced portfolio still charts.
+ * The `--wide` pivot is read the same way, except its `usd_total` column is
+ * already one value per sample: `--wide`, `--wide --usd`, and `--wide
+ * --usd-only` all chart from it without summing asset columns.
+ */
+export declare function buildPlotReport(text: string, options: {
+    path: string;
+    width?: number;
+}): PlotReport;
+/** One line of block characters: the smallest value is lowest, the largest is full. */
+export declare function sparkline(values: number[], width?: number): string;
+export declare function formatPlot(report: PlotReport): string;
+export declare function toPlotJson(report: PlotReport): Record<string, unknown>;