dexterm-cli 0.0.0-stage → 0.1.1

package/dist/packages/data/src/health.js

@@ -0,0 +1,245 @@
+// Per-source health registry (SPEC §3.5, learning CL-08).
+//
+// Rules: three consecutive failures, or two 429s inside a minute, flip a source
+// to `degraded` for a backoff window (30 s, doubling per repeat up to 10 min).
+// When the window ends the source is `probing` (half-open): requests are allowed
+// again, one success returns it to `ok` and resets the backoff, one failure
+// re-degrades it with the doubled window. Keyed sources without a key are
+// `needs-key`; feature-flagged sources can be `disabled`.
+//
+// The registry gates which columns, features and AI tools are offered.
+import { systemClock } from "./clock.js";
+export const DEFAULT_HEALTH_POLICY = {
+    failureThreshold: 3,
+    rateLimitThreshold: 2,
+    rateLimitWindowMs: 60_000,
+    baseBackoffMs: 30_000,
+    maxBackoffMs: 600_000,
+};
+/** Sources that cannot work without a user-supplied key (SPEC §3.2 Tier 1). */
+export const KEYED_SOURCES = new Set(['helius', 'birdeye']);
+export class HealthRegistry {
+    entries = new Map();
+    clock;
+    policy;
+    keys;
+    disabled;
+    usage;
+    listeners = new Set();
+    constructor(opts = {}) {
+        this.clock = opts.clock ?? systemClock;
+        this.policy = { ...DEFAULT_HEALTH_POLICY, ...opts.policy };
+        this.keys = { ...opts.keys };
+        this.disabled = new Set(opts.disabled ?? []);
+        this.usage = opts.usage;
+    }
+    onChange(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+    setKey(source, present) {
+        const before = this.state(source);
+        this.keys[source] = present;
+        this.rebase(source);
+        this.emitIfChanged(source, before);
+    }
+    setDisabled(source, disabled) {
+        const before = this.state(source);
+        if (disabled)
+            this.disabled.add(source);
+        else
+            this.disabled.delete(source);
+        this.rebase(source);
+        this.emitIfChanged(source, before);
+    }
+    /** Re-derive key/flag state; a degraded source stays degraded unless it is now gated off. */
+    rebase(source) {
+        const e = this.entry(source);
+        const base = this.initialBase(source);
+        if (e.base !== 'degraded' || base !== 'ok') {
+            if (e.base !== base)
+                e.since = this.clock.now();
+            e.base = base;
+        }
+    }
+    /** Record the outcome of one call to `source`. */
+    record(source, outcome) {
+        const now = this.clock.now();
+        const before = this.state(source);
+        const e = this.entry(source);
+        if (outcome.latencyMs !== undefined)
+            e.latencyMs = outcome.latencyMs;
+        if (outcome.ok) {
+            e.okCount++;
+            e.consecutiveFailures = 0;
+            if (e.base === 'degraded') {
+                e.base = 'ok';
+                e.since = now;
+                e.degradedUntil = 0;
+                e.backoffMs = 0;
+                e.nextBackoffMs = this.policy.baseBackoffMs;
+            }
+        }
+        else {
+            e.errorCount++;
+            e.consecutiveFailures++;
+            e.lastError = outcome.error ?? (outcome.status ? `HTTP ${outcome.status}` : 'error');
+            if (outcome.status === 429)
+                e.recent429.push(now);
+            e.recent429 = e.recent429.filter((t) => t > now - this.policy.rateLimitWindowMs);
+            const probing = before === 'probing';
+            const tripped = e.consecutiveFailures >= this.policy.failureThreshold || e.recent429.length >= this.policy.rateLimitThreshold;
+            if ((probing || tripped) && (e.base === 'ok' || e.base === 'degraded') && before !== 'degraded') {
+                this.degrade(e, now);
+            }
+        }
+        this.emitIfChanged(source, before);
+    }
+    state(source) {
+        const e = this.entry(source);
+        if (e.base === 'degraded')
+            return this.clock.now() >= e.degradedUntil ? 'probing' : 'degraded';
+        return e.base;
+    }
+    /** True when requests to `source` should be attempted (ok or probing). */
+    isAvailable(source) {
+        const s = this.state(source);
+        return s === 'ok' || s === 'probing';
+    }
+    get(source) {
+        const e = this.entry(source);
+        return {
+            source,
+            state: this.state(source),
+            since: e.since,
+            consecutiveFailures: e.consecutiveFailures,
+            degradedUntil: e.degradedUntil,
+            backoffMs: e.backoffMs,
+            latencyMs: e.latencyMs,
+            lastError: e.lastError,
+            okCount: e.okCount,
+            errorCount: e.errorCount,
+        };
+    }
+    /** SPEC §3.3 `Health` records for every source seen (or the ones asked for). */
+    snapshot(sources) {
+        const ids = sources ?? [...this.entries.keys()];
+        return ids.map((source) => {
+            const h = this.get(source);
+            const u = this.usage?.(source);
+            return {
+                source,
+                ok: h.state === 'ok' || h.state === 'probing',
+                state: h.state === 'probing' ? 'degraded' : h.state,
+                latencyMs: h.latencyMs ?? null,
+                rpmUsed: u?.rpmUsed ?? 0,
+                rpmLimit: u?.rpmLimit ?? null,
+                lastError: h.lastError ?? null,
+                since: h.since,
+            };
+        });
+    }
+    degrade(e, now) {
+        e.base = 'degraded';
+        e.since = now;
+        e.backoffMs = e.nextBackoffMs;
+        e.degradedUntil = now + e.backoffMs;
+        e.nextBackoffMs = Math.min(e.nextBackoffMs * 2, this.policy.maxBackoffMs);
+        e.consecutiveFailures = 0;
+        e.recent429 = [];
+    }
+    initialBase(source) {
+        if (this.disabled.has(source))
+            return 'disabled';
+        if (KEYED_SOURCES.has(source) && !this.keys[source])
+            return 'needs-key';
+        return 'ok';
+    }
+    entry(source) {
+        let e = this.entries.get(source);
+        if (!e) {
+            e = {
+                source,
+                base: this.initialBase(source),
+                since: this.clock.now(),
+                consecutiveFailures: 0,
+                recent429: [],
+                degradedUntil: 0,
+                backoffMs: 0,
+                nextBackoffMs: this.policy.baseBackoffMs,
+                okCount: 0,
+                errorCount: 0,
+            };
+            this.entries.set(source, e);
+        }
+        return e;
+    }
+    emitIfChanged(source, before) {
+        const after = this.state(source);
+        if (after !== before)
+            for (const fn of this.listeners)
+                fn(source, after);
+    }
+}
+/** Screener columns (SPEC §4.2) and the sources that can fill them. */
+export const COLUMN_SOURCES = {
+    // Jupiter Tokens v2 carries price/stats too, so these survive a DexScreener outage.
+    price: { anyOf: ['dexscreener', 'jupiter-tokens', 'jupiter-price'] },
+    '5m': { anyOf: ['dexscreener', 'jupiter-tokens'] },
+    '1h': { anyOf: ['dexscreener', 'jupiter-tokens'] },
+    '6h': { anyOf: ['dexscreener', 'jupiter-tokens'] },
+    '24h': { anyOf: ['dexscreener', 'jupiter-tokens'] },
+    vol: { anyOf: ['dexscreener', 'jupiter-tokens'] },
+    liq: { anyOf: ['dexscreener', 'jupiter-tokens'] },
+    mcap: { anyOf: ['dexscreener', 'jupiter-tokens'] },
+    age: { anyOf: ['dexscreener', 'jupiter-tokens'] },
+    bs: { anyOf: ['dexscreener', 'jupiter-tokens'], label: 'buy/sell txns' },
+    sparkline: { anyOf: ['dexscreener', 'jupiter-tokens'], label: 'local history of polled prices' },
+    holders: { anyOf: ['jupiter-tokens'] },
+    org: { anyOf: ['jupiter-tokens'], label: 'organic score' },
+    flags: { anyOf: ['jupiter-tokens', 'solana-rpc', 'helius', 'goplus'], label: 'mint/freeze authority' },
+    launchpad: { anyOf: ['jupiter-tokens'] },
+    bonding: { anyOf: ['pumpfun', 'pumpportal'] },
+    dev: { anyOf: ['jupiter-tokens', 'helius'] },
+    snipers: { anyOf: ['helius'] },
+    bundled: { anyOf: ['helius'] },
+};
+/** Screens, panels and AI tools that depend on specific sources (SPEC §3.2, §5.2). */
+export const FEATURE_SOURCES = {
+    screener: { anyOf: ['dexscreener', 'jupiter-tokens'] },
+    'sol-price': { anyOf: ['jupiter-price', 'dexscreener'] },
+    candles: { anyOf: ['geckoterminal', 'birdeye'] },
+    'top-holders': { anyOf: ['helius', 'solana-rpc'] },
+    'new-pairs-live': { anyOf: ['pumpportal', 'jupiter-tokens'] },
+    rugcheck: { anyOf: ['rugcheck'] },
+    security: { anyOf: ['rugcheck', 'goplus'], label: 'risk opinions' },
+    authorities: { anyOf: ['helius', 'solana-rpc', 'goplus', 'jupiter-tokens'] },
+    forensics: { anyOf: ['helius'] },
+    'dev-history': { anyOf: ['helius', 'jupiter-tokens'] },
+    'top-traders': { anyOf: ['birdeye', 'helius'] },
+    'live-tape': { anyOf: ['geckoterminal', 'helius'] },
+    'new-pairs-poll': { anyOf: ['jupiter-tokens', 'rugcheck'] },
+    // Paper trading (task-1310): the ticket prices fills from the keyless swap quote only.
+    'trade-quote': { anyOf: ['jupiter-swap'], label: 'paper trade quote' },
+};
+const GATE_RANK = { ok: 0, degraded: 1, 'needs-key': 2, disabled: 3 };
+export function gate(registry, id, spec) {
+    const via = spec.anyOf.filter((s) => registry.isAvailable(s));
+    if (via.length > 0)
+        return { id, state: 'ok', available: true, via };
+    // Report the most actionable reason: degraded beats needs-key beats disabled.
+    let best = 'disabled';
+    for (const s of spec.anyOf) {
+        const st = registry.state(s);
+        const g = st === 'degraded' ? 'degraded' : st === 'needs-key' ? 'needs-key' : st === 'disabled' ? 'disabled' : 'ok';
+        if (GATE_RANK[g] < GATE_RANK[best])
+            best = g;
+    }
+    return { id, state: best, available: false, via };
+}
+export function gateAll(registry, specs) {
+    const out = {};
+    for (const [id, spec] of Object.entries(specs))
+        out[id] = gate(registry, id, spec);
+    return out;
+}

package/dist/packages/data/src/http.js

@@ -0,0 +1,277 @@
+// Keyless, read-only HTTP client. Every call goes through the health gate and
+// the rate limiter, is timed, and reports its outcome to the health registry.
+// GET for REST sources; POST only for JSON-RPC reads (the Solana RPC adapter
+// allow-lists read-only methods), never with auth headers.
+// The transport is pluggable: live fetch, recorder (live + capture) or replayer
+// (fixtures only, never touches the network).
+import { systemClock } from "./clock.js";
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { PriorityRef } from "./limiter.js";
+import { redactSecrets } from "./rpc-config.js";
+/** Response headers worth keeping (rate-limit hints); everything else is dropped. */
+const KEEP_HEADERS = ['content-type', 'retry-after', 'x-ratelimit-limit', 'x-ratelimit-remaining', 'x-ratelimit-reset'];
+/** Real network via global fetch. GET only, no auth headers, no cookies. */
+export function liveTransport(opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 10_000;
+    const userAgent = opts.userAgent ?? 'dexterm/0.0.1 (+local terminal screener; keyless read-only)';
+    const shutdownSignal = opts.shutdownSignal;
+    return async (req) => {
+        const t0 = performance.now();
+        const headers = { accept: req.accept ?? 'application/json', 'user-agent': userAgent };
+        if (req.body !== undefined)
+            headers['content-type'] = 'application/json';
+        // Own the timeout + shutdown abort via one controller instead of AbortSignal.timeout(): the latter
+        // schedules an internal *ref'd* timer that is never cancelled when the fetch settles (or when a
+        // companion signal fires), so each live request left a ref'd ~10 s timer keeping the event loop
+        // alive — the 10-33 s quit hang (task-1319, QA M1). This timer is unref'd (never holds the loop on
+        // its own) and cleared the instant the request settles, and the shutdown signal aborts it at once.
+        // The caller may also pass its own abort (task-1310: bounded confirm quote); whichever fires first wins.
+        const controller = new AbortController();
+        const onTimeout = () => controller.abort(new DOMException(`timed out after ${timeoutMs}ms`, 'TimeoutError'));
+        const onShutdown = () => controller.abort(new DOMException('shutting down', 'AbortError'));
+        const onCaller = () => controller.abort(req.signal?.reason ?? new DOMException('aborted by caller', 'AbortError'));
+        const timer = setTimeout(onTimeout, timeoutMs);
+        timer.unref?.();
+        if (shutdownSignal) {
+            if (shutdownSignal.aborted)
+                onShutdown();
+            else
+                shutdownSignal.addEventListener('abort', onShutdown, { once: true });
+        }
+        if (req.signal) {
+            if (req.signal.aborted)
+                onCaller();
+            else
+                req.signal.addEventListener('abort', onCaller, { once: true });
+        }
+        try {
+            const res = await globalThis.fetch(req.url, {
+                method: req.method,
+                headers,
+                body: req.body,
+                signal: controller.signal,
+            });
+            const body = await res.text();
+            const kept = {};
+            for (const h of KEEP_HEADERS) {
+                const v = res.headers.get(h);
+                if (v !== null)
+                    kept[h] = v;
+            }
+            return { status: res.status, headers: kept, body, latencyMs: Math.round(performance.now() - t0) };
+        }
+        finally {
+            clearTimeout(timer);
+            shutdownSignal?.removeEventListener('abort', onShutdown);
+            req.signal?.removeEventListener('abort', onCaller);
+        }
+    };
+}
+/**
+ * Parse a `Retry-After` header (seconds) to ms; undefined when absent or not a positive number. task-1368:
+ * Jupiter's keyless gateway sends NO Retry-After on a 429 (recorded 2026-10-12, fixtures/trade/jupiter-429-*.json)
+ * but does send `x-ratelimit-reset` (epoch seconds), so when Retry-After is absent the wait is derived from the
+ * reset time instead — the honest number for "retry in Ns" and for the retry policy.
+ */
+function retryAfterMs(res, now) {
+    const v = Number(res.headers['retry-after']);
+    if (Number.isFinite(v) && v > 0)
+        return v * 1000;
+    if (now !== undefined) {
+        const reset = Number(res.headers['x-ratelimit-reset']);
+        if (Number.isFinite(reset) && reset > 0) {
+            const until = reset * 1000 - now;
+            if (until > 0)
+                return Math.min(until, MAX_HEADER_PAUSE_MS);
+        }
+    }
+    return undefined;
+}
+const MAX_HEADER_PAUSE_MS = 60_000;
+/** Cap for the doubling pause after consecutive 429s on one bucket (matches the health backoff cap). */
+const MAX_429_PAUSE_MS = 600_000;
+export class HttpError extends Error {
+    status;
+    url;
+    /** Retry-After in ms when the server sent one (429/503); used by the RPC pool to pause an endpoint. */
+    retryAfterMs;
+    constructor(status, url, message, retryAfterMs) {
+        // URLs may carry an RPC api-key: never let one into a message that can reach a log or the screen.
+        super(redactSecrets(message ?? `HTTP ${status} for ${url}`));
+        this.name = 'HttpError';
+        this.status = status;
+        this.url = redactSecrets(url);
+        if (retryAfterMs !== undefined)
+            this.retryAfterMs = retryAfterMs;
+    }
+}
+export class SourceUnavailableError extends Error {
+    source;
+    constructor(source, state) {
+        super(`source ${source} is ${state}`);
+        this.name = 'SourceUnavailableError';
+        this.source = source;
+    }
+}
+/**
+ * Request priority context (task-1323). Code that knows how urgent its requests are wraps the call:
+ * `withPriority('high', () => dl.detail.candles(...))`; every request issued inside (through any number
+ * of awaits, caches and adapters) is queued at that priority in its rate bucket. Without a context a
+ * request is 'normal' — the pre-1323 behaviour. Passing a PriorityRef shares it, so a later raise()
+ * (a foreground caller coalescing onto a background load) re-prioritises requests already queued.
+ */
+const priorityContext = new AsyncLocalStorage();
+export function withPriority(priority, fn) {
+    return priorityContext.run(typeof priority === 'string' ? new PriorityRef(priority) : priority, fn);
+}
+/** The caller's priority context, if any (undefined = normal). */
+export function currentPriority() {
+    return priorityContext.getStore();
+}
+export class HttpClient {
+    opts;
+    /** The clock every wait in this client runs on (a FakeClock in tests); adapters pace their own retries by it. */
+    clock;
+    inflight = new Map();
+    /** Consecutive 429s per bucket, for the doubling pause. Reset by any non-429 response. */
+    strikes = new Map();
+    constructor(opts) {
+        this.opts = opts;
+        this.clock = opts.clock ?? systemClock;
+    }
+    /** GET JSON. Identical in-flight URLs share one request (SPEC §3.4 coalescing). */
+    getJson(url, meta, check, signal) {
+        return this.coalesce(`GET ${url}`, { method: 'GET', url, signal }, meta, check);
+    }
+    /**
+     * POST a JSON body (JSON-RPC reads only). Identical in-flight url+body pairs share one request.
+     * `signal` (task-1368) bounds the wait like getJson's: a caller deadline cuts the limiter queue and the
+     * transport, and an abortable POST is never shared.
+     */
+    postJson(url, body, meta, check, signal) {
+        const text = JSON.stringify(body);
+        return this.coalesce(`POST ${url} ${text}`, { method: 'POST', url, body: text, signal }, meta, check);
+    }
+    /** Ms until a DEGRADED source is probed again (0 when it is available or unknown). The health gate's own cool-down. */
+    unavailableFor(source) {
+        try {
+            const h = this.opts.health.get(source);
+            return h.state === 'degraded' ? Math.max(0, h.degradedUntil - this.clock.now()) : 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /** Remaining pause on a rate bucket in ms (0 when it is not paused or unknown). For honest "retry in Ns" messages. */
+    pausedFor(bucket) {
+        try {
+            const until = this.opts.limiter.bucket(bucket).stats().pausedUntil;
+            return until > 0 ? Math.max(0, until - this.clock.now()) : 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /**
+     * GET a text document (task-1330: RSS/XML news feeds). Same gate, limiter, health accounting,
+     * coalescing and rate-limit header handling as getJson; the body is returned unparsed.
+     */
+    getText(url, meta, accept = 'application/rss+xml, application/xml, text/xml;q=0.9, */*;q=0.5') {
+        return this.coalesce(`GET ${url}`, { method: 'GET', url, accept }, meta, undefined, true);
+    }
+    coalesce(key, req, meta, check, raw = false) {
+        const caller = currentPriority();
+        // An abortable request is never shared (task-1310): a caller that cancels (e.g. a bounded confirm
+        // quote) must not cancel an unrelated caller, and must not be ignored by joining a non-abortable one.
+        if (req.signal)
+            return this.doRequest(req, meta, check, new PriorityRef(caller?.level ?? 'normal'));
+        const existing = this.inflight.get(key);
+        if (existing) {
+            // A more urgent caller joining a queued request lifts it (task-1323): never inherit a lower priority.
+            if (caller)
+                existing.ref.raise(caller.level);
+            return existing.p;
+        }
+        // Each request gets its own ref seeded from the caller's level and following the caller's raises,
+        // so raising one coalesced request does not re-prioritise unrelated requests of the same caller.
+        const ref = new PriorityRef(caller?.level ?? 'normal');
+        const off = caller ? caller.on(() => ref.raise(caller.level)) : null;
+        const p = this.doRequest(req, meta, check, ref, raw).finally(() => { this.inflight.delete(key); off?.(); });
+        this.inflight.set(key, { p: p, ref });
+        return p;
+    }
+    /**
+     * 429 -> pause (Retry-After, or the default doubling per consecutive 429 on the bucket);
+     * `x-ratelimit-remaining: 0` -> pause until reset (capped).
+     */
+    respectRateLimitHeaders(res, meta, rateLimited = res.status === 429) {
+        const { limiter } = this.opts;
+        if (rateLimited) {
+            const n = (this.strikes.get(meta.bucket) ?? 0) + 1;
+            this.strikes.set(meta.bucket, n);
+            const base = this.opts.rateLimitPauseMs ?? 30_000;
+            const backoff = Math.min(base * 2 ** (n - 1), MAX_429_PAUSE_MS);
+            // The server's own wait (Retry-After, else its x-ratelimit-reset — task-1368) governs the first strike;
+            // a repeated 429 on the same bucket never pauses less than the doubling backoff.
+            const stated = retryAfterMs(res, this.clock.now());
+            limiter.pause(meta.bucket, stated !== undefined ? Math.max(stated, n > 1 ? backoff : 0) : backoff);
+        }
+        else {
+            this.strikes.delete(meta.bucket);
+        }
+        if (res.headers['x-ratelimit-remaining'] === '0') {
+            const reset = Number(res.headers['x-ratelimit-reset']); // epoch seconds (Jupiter)
+            const until = Number.isFinite(reset) && reset > 0 ? reset * 1000 - this.clock.now() : 10_000;
+            limiter.pause(meta.bucket, Math.min(Math.max(until, 1_000), MAX_HEADER_PAUSE_MS));
+        }
+    }
+    async doRequest(req, meta, check, priority, raw = false) {
+        const { health, limiter, transport } = this.opts;
+        const url = req.url;
+        if (!health.isAvailable(meta.source))
+            throw new SourceUnavailableError(meta.source, health.state(meta.source));
+        // Pass the caller's abort to the limiter so a bounded wait is cut even while queued behind a
+        // 429 pause (task-1310): the confirm-time quote can never hang past its deadline in the bucket.
+        await limiter.acquire(meta.bucket, req.signal, priority);
+        let res;
+        try {
+            res = await transport(req);
+        }
+        catch (err) {
+            const msg = redactSecrets(err instanceof Error ? err.message : String(err));
+            health.record(meta.source, { ok: false, error: msg });
+            this.opts.onRequest?.(req, meta, { status: null, latencyMs: 0 });
+            throw err;
+        }
+        this.opts.onRequest?.(req, meta, { status: res.status, latencyMs: res.latencyMs });
+        if (res.status < 200 || res.status >= 300) {
+            this.respectRateLimitHeaders(res, meta);
+            health.record(meta.source, { ok: false, status: res.status, latencyMs: res.latencyMs });
+            throw new HttpError(res.status, url, undefined, retryAfterMs(res, this.clock.now()));
+        }
+        if (raw) {
+            // Text document (RSS/XML): no JSON parse, no body check; headers still drive the limiter.
+            this.respectRateLimitHeaders(res, meta);
+            health.record(meta.source, { ok: true, status: res.status, latencyMs: res.latencyMs });
+            return { data: res.body, status: res.status, latencyMs: res.latencyMs, fetchedAt: this.clock.now() };
+        }
+        let data;
+        try {
+            data = JSON.parse(res.body);
+        }
+        catch {
+            this.respectRateLimitHeaders(res, meta);
+            health.record(meta.source, { ok: false, status: res.status, latencyMs: res.latencyMs, error: 'invalid JSON' });
+            throw new HttpError(res.status, url, `invalid JSON from ${url}`);
+        }
+        const bad = check?.(data);
+        this.respectRateLimitHeaders(res, meta, bad?.status === 429);
+        if (bad) {
+            const status = bad.status ?? res.status;
+            health.record(meta.source, { ok: false, status, latencyMs: res.latencyMs, error: bad.error });
+            throw new HttpError(status, url, `${bad.error} (${url})`, retryAfterMs(res, this.clock.now()));
+        }
+        health.record(meta.source, { ok: true, status: res.status, latencyMs: res.latencyMs });
+        return { data, status: res.status, latencyMs: res.latencyMs, fetchedAt: this.clock.now() };
+    }
+}

package/dist/packages/data/src/images/cache.js

@@ -0,0 +1,141 @@
+// @dexterm/data — on-disk coin-image cache (task-1326). Lives under the app data dir (next to dexterm.db):
+// `<dir>/images/<sha256(url)[0..31]>.png` holds OUR re-encoded thumbnail (never the bytes the host sent),
+// so nothing downstream — the popup page, a future export — ever parses third-party image data. A
+// `.fail` marker remembers a refused/undecodable URL for a while so a dead IPFS link is not retried on
+// every launch. LRU by file mtime: a hit touches the file; when the directory grows past `maxBytes` the
+// oldest files go. Every filesystem failure is swallowed (a cache must never break the app).
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync, readdirSync, statSync, unlinkSync, utimesSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+export function imageCacheKey(url) {
+    return createHash('sha256').update(url).digest('hex').slice(0, 32);
+}
+export class ImageDiskCache {
+    dir;
+    maxBytes;
+    failTtlMs;
+    now;
+    ready = false;
+    lastTouch = new Map();
+    stats = { files: 0, bytes: 0, hits: 0, misses: 0, writes: 0, evictions: 0 };
+    constructor(opts) {
+        this.dir = opts.dir;
+        this.maxBytes = opts.maxBytes ?? 32 * 1024 * 1024;
+        this.failTtlMs = opts.failTtlMs ?? 6 * 3_600_000;
+        this.now = opts.now ?? (() => Date.now());
+    }
+    ensure() {
+        if (this.ready)
+            return true;
+        try {
+            mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+            this.ready = true;
+        }
+        catch { /* unwritable: cache off */ }
+        return this.ready;
+    }
+    pathFor(key, ext) { return join(this.dir, `${key}.${ext}`); }
+    /** Our stored thumbnail PNG for a URL key, or null. Touches the file (LRU). */
+    get(key) {
+        if (!this.ensure())
+            return null;
+        try {
+            const p = this.pathFor(key, 'png');
+            const buf = readFileSync(p);
+            this.stats.hits += 1;
+            const t = this.now();
+            if ((this.lastTouch.get(key) ?? 0) + 600_000 < t) {
+                this.lastTouch.set(key, t);
+                try {
+                    utimesSync(p, new Date(t), new Date(t));
+                }
+                catch { /* read-only fs: LRU just degrades */ }
+            }
+            return buf;
+        }
+        catch {
+            this.stats.misses += 1;
+            return null;
+        }
+    }
+    /** True when a failure marker younger than failTtl exists for this key (the marker carries its own timestamp). */
+    failed(key) {
+        if (!this.ensure())
+            return false;
+        try {
+            const text = readFileSync(this.pathFor(key, 'fail'), 'utf8');
+            const at = Number(text.split('\n')[0]);
+            return Number.isFinite(at) && this.now() - at < this.failTtlMs;
+        }
+        catch {
+            return false;
+        }
+    }
+    markFailed(key, reason) {
+        if (!this.ensure())
+            return;
+        try {
+            writeFileSync(this.pathFor(key, 'fail'), `${this.now()}\n${reason.slice(0, 200)}`, { mode: 0o600 });
+        }
+        catch { /* ignore */ }
+    }
+    /** Store our PNG thumbnail (atomic rename), then evict the oldest files past the byte cap. */
+    put(key, png) {
+        if (!this.ensure())
+            return;
+        try {
+            const p = this.pathFor(key, 'png');
+            const tmp = `${p}.${process.pid}.tmp`;
+            writeFileSync(tmp, png, { mode: 0o600 });
+            renameSync(tmp, p);
+            try {
+                const t = new Date(this.now());
+                utimesSync(p, t, t);
+            }
+            catch { /* LRU just degrades */ }
+            try {
+                unlinkSync(this.pathFor(key, 'fail'));
+            }
+            catch { /* no marker */ }
+            this.stats.writes += 1;
+            this.lastTouch.set(key, this.now());
+            this.evict();
+        }
+        catch { /* ignore */ }
+    }
+    /** Drop oldest files until the directory is under the cap. Also measures the directory. */
+    evict() {
+        let entries = [];
+        try {
+            for (const name of readdirSync(this.dir)) {
+                if (!name.endsWith('.png') && !name.endsWith('.fail'))
+                    continue;
+                try {
+                    const st = statSync(join(this.dir, name));
+                    entries.push({ name, size: st.size, mtime: st.mtimeMs });
+                }
+                catch { /* vanished */ }
+            }
+        }
+        catch {
+            return;
+        }
+        let total = entries.reduce((s, e) => s + e.size, 0);
+        this.stats.files = entries.length;
+        if (total > this.maxBytes) {
+            entries = entries.sort((a, b) => a.mtime - b.mtime);
+            for (const e of entries) {
+                if (total <= this.maxBytes * 0.9)
+                    break;
+                try {
+                    unlinkSync(join(this.dir, e.name));
+                    total -= e.size;
+                    this.stats.evictions += 1;
+                    this.stats.files -= 1;
+                }
+                catch { /* ignore */ }
+            }
+        }
+        this.stats.bytes = total;
+    }
+}