@cogcoin/client 1.0.1 → 1.0.2

package/dist/cli/prompt.js

@@ -1,5 +1,9 @@
 import { createInterface } from "node:readline/promises";
 const CLEAR_SENSITIVE_DISPLAY_SEQUENCE = "\u001B[2J\u001B[3J\u001B[H";
+const CLEAR_MENU_SEQUENCE = "\u001B[0J";
+function countRenderedLines(text) {
+    return text.endsWith("\n") ? text.split("\n").length - 1 : text.split("\n").length;
+}
 export function createTerminalPrompter(input, output) {
     const ensureReadableInput = () => {
         if (!("on" in input) || !("off" in input)) {
@@ -8,6 +12,12 @@ export function createTerminalPrompter(input, output) {
         return input;
     };
     const ensureWritableOutput = () => output;
+    const supportsRawSelection = () => {
+        const readable = ensureReadableInput();
+        return Boolean(readable.isTTY
+            && output.isTTY
+            && typeof readable.setRawMode === "function");
+    };
     const ask = async (message, questionOutput) => {
         const readline = createInterface({
             input: ensureReadableInput(),
@@ -20,6 +30,99 @@ export function createTerminalPrompter(input, output) {
             readline.close();
         }
     };
+    const promptSelectionFallback = async (options) => {
+        const writableOutput = ensureWritableOutput();
+        writableOutput.write(`${options.message}\n`);
+        for (const [index, option] of options.options.entries()) {
+            const description = option.description == null || option.description.length === 0
+                ? ""
+                : ` - ${option.description}`;
+            writableOutput.write(`${index + 1}. ${option.label}${description}\n`);
+        }
+        if (options.footer != null && options.footer.length > 0) {
+            writableOutput.write(`${options.footer}\n`);
+        }
+        while (true) {
+            const answer = (await ask(`Choice [1-${options.options.length}]: `, writableOutput)).trim();
+            if (/^(q|quit|esc|escape)$/i.test(answer)) {
+                throw new Error("mining_setup_canceled");
+            }
+            const selection = Number.parseInt(answer, 10);
+            if (Number.isInteger(selection) && selection >= 1 && selection <= options.options.length) {
+                return options.options[selection - 1].value;
+            }
+            writableOutput.write(`Enter a number from 1 to ${options.options.length}, or q to cancel.\n`);
+        }
+    };
+    const promptSelectionRaw = async (options) => {
+        const readableInput = ensureReadableInput();
+        const writableOutput = ensureWritableOutput();
+        const initialIndex = options.initialValue == null
+            ? -1
+            : options.options.findIndex((option) => option.value === options.initialValue);
+        let selectedIndex = initialIndex === -1 ? 0 : initialIndex;
+        let renderedLineCount = 0;
+        const renderMenu = () => {
+            if (renderedLineCount > 0) {
+                writableOutput.write(`\u001B[${renderedLineCount}A${CLEAR_MENU_SEQUENCE}`);
+            }
+            const lines = [
+                options.message,
+                "Use Up/Down to choose, Enter to confirm, or q/Esc/Ctrl+C to cancel.",
+                ...options.options.map((option, index) => {
+                    const prefix = index === selectedIndex ? ">" : " ";
+                    const description = option.description == null || option.description.length === 0
+                        ? ""
+                        : ` - ${option.description}`;
+                    return `${prefix} ${option.label}${description}`;
+                }),
+            ];
+            if (options.footer != null && options.footer.length > 0) {
+                lines.push(options.footer);
+            }
+            const rendered = `${lines.join("\n")}\n`;
+            renderedLineCount = countRenderedLines(rendered);
+            writableOutput.write(rendered);
+        };
+        return await new Promise((resolve, reject) => {
+            const finish = (handler) => {
+                readableInput.off("data", onData);
+                readableInput.setRawMode(false);
+                readableInput.pause?.();
+                writableOutput.write("\n");
+                handler();
+            };
+            const onData = (chunk) => {
+                const value = Buffer.isBuffer(chunk) ? chunk.toString("utf8") : chunk;
+                switch (value) {
+                    case "\u001B[A":
+                        selectedIndex = selectedIndex === 0 ? options.options.length - 1 : selectedIndex - 1;
+                        renderMenu();
+                        return;
+                    case "\u001B[B":
+                        selectedIndex = selectedIndex === options.options.length - 1 ? 0 : selectedIndex + 1;
+                        renderMenu();
+                        return;
+                    case "\r":
+                    case "\n":
+                        finish(() => resolve(options.options[selectedIndex].value));
+                        return;
+                    case "\u001B":
+                    case "\u0003":
+                    case "q":
+                    case "Q":
+                        finish(() => reject(new Error("mining_setup_canceled")));
+                        return;
+                    default:
+                        return;
+                }
+            };
+            readableInput.setRawMode(true);
+            readableInput.resume?.();
+            readableInput.on("data", onData);
+            renderMenu();
+        });
+    };
     return {
         isInteractive: Boolean(input.isTTY && output.isTTY),
         writeLine(message) {
@@ -44,6 +147,12 @@ export function createTerminalPrompter(input, output) {
                 output.write("\n");
             }
         },
+        async selectOption(options) {
+            if (!supportsRawSelection()) {
+                return await promptSelectionFallback(options);
+            }
+            return await promptSelectionRaw(options);
+        },
         clearSensitiveDisplay(scope) {
             if (!input.isTTY || !output.isTTY) {
                 return;

package/dist/cli/read-json.d.ts

@@ -114,6 +114,19 @@ export declare function buildMineStatusJson(mining: MiningControlPlaneView): Rea
     phase: string;
     lastSuspendDetectedAtUnixMs: number | null;
     pauseReason: string | null;
+    providerState: string | null;
+    provider: {
+        configured: boolean;
+        kind: string | null;
+        modelId: string | null;
+        effectiveModel: string | null;
+        modelOverride: string | null;
+        modelSelectionSource: string | null;
+        usingDefaultModel: boolean | null;
+        extraPromptConfigured: boolean;
+        estimatedDailyCostUsd: number | null;
+        estimatedDailyCostDisplay: string | null;
+    };
     fees: Record<string, unknown>;
     worker: Record<string, unknown>;
     availability: Record<string, JsonAvailabilityEntry>;

package/dist/cli/read-json.js

@@ -288,6 +288,18 @@ function buildMiningStatusData(mining) {
         phase: mining.runtime.currentPhase,
         lastSuspendDetectedAtUnixMs: mining.runtime.lastSuspendDetectedAtUnixMs,
         pauseReason: mining.runtime.pauseReason,
+        provider: {
+            configured: mining.provider.configured,
+            kind: mining.provider.provider,
+            modelId: mining.provider.modelId,
+            effectiveModel: mining.provider.effectiveModel,
+            modelOverride: mining.provider.modelOverride,
+            modelSelectionSource: mining.provider.modelSelectionSource,
+            usingDefaultModel: mining.provider.usingDefaultModel,
+            extraPromptConfigured: mining.provider.extraPromptConfigured,
+            estimatedDailyCostUsd: mining.provider.estimatedDailyCostUsd,
+            estimatedDailyCostDisplay: mining.provider.estimatedDailyCostDisplay,
+        },
         providerState: mining.runtime.providerState,
         tipsAligned: mining.runtime.tipsAligned,
         sameDomainCompetitorSuppressed: mining.runtime.sameDomainCompetitorSuppressed,
@@ -393,6 +405,11 @@ export function buildMineStatusJson(mining) {
     if (mining.runtime.miningState === "repair-required") {
         nextSteps.push("Run `cogcoin repair` before mining again.");
     }
+    else if (mining.runtime.providerState === "not-found") {
+        nextSteps.push(mining.provider.usingDefaultModel === false
+            ? "Run `cogcoin mine setup` and clear or correct the provider model."
+            : "Run `cogcoin mine setup` and choose a valid provider model.");
+    }
     else if (mining.runtime.pauseReason === "zero-reward") {
         nextSteps.push("Wait for the next positive-reward target height; mining resumes automatically.");
     }

package/dist/cli/runner.js

@@ -10,6 +10,7 @@ import { runMiningRuntimeCommand } from "./commands/mining-runtime.js";
 import { runServiceRuntimeCommand } from "./commands/service-runtime.js";
 import { runStatusCommand } from "./commands/status.js";
 import { runSyncCommand } from "./commands/sync.js";
+import { runUpdateCommand } from "./commands/update.js";
 import { runWalletAdminCommand } from "./commands/wallet-admin.js";
 import { runWalletMutationCommand } from "./commands/wallet-mutation.js";
 import { runWalletReadCommand } from "./commands/wallet-read.js";
@@ -52,6 +53,9 @@ export async function runCli(argv, contextOverrides = {}) {
     }
     await maybeNotifyAboutCliUpdate(parsed, context);
     try {
+        if (parsed.command === "update") {
+            return runUpdateCommand(parsed, context);
+        }
         if (commandUsesExistingWalletSeed(parsed)) {
             const mainPaths = context.resolveWalletRuntimePaths("main");
             const seedIndex = await loadWalletSeedIndex({

package/dist/cli/types.d.ts

@@ -14,7 +14,7 @@ import type { ensureBuiltInMiningSetupIfNeeded, followMiningLog, inspectMiningCo
 import type { anchorDomain, transferBitcoin, buyDomain, claimCogLock, clearDomainDelegate, clearDomainEndpoint, clearDomainMiner, clearField, createField, giveReputation, lockCogToDomain, registerDomain, reclaimCogLock, revokeReputation, sendCog, setField, setDomainCanonical, setDomainDelegate, setDomainEndpoint, setDomainMiner, sellDomain, transferDomain } from "../wallet/tx/index.js";
 export type ProgressOutput = "auto" | "tty" | "none";
 export type OutputMode = "text" | "json" | "preview-json";
-export type CommandName = "init" | "restore" | "reset" | "repair" | "sync" | "status" | "client-lock" | "client-change-password" | "client-unlock" | "follow" | "bitcoin-start" | "bitcoin-stop" | "bitcoin-status" | "bitcoin-transfer" | "indexer-start" | "indexer-stop" | "indexer-status" | "anchor" | "domain-anchor" | "register" | "domain-register" | "transfer" | "domain-transfer" | "sell" | "domain-sell" | "unsell" | "domain-unsell" | "buy" | "domain-buy" | "domain-endpoint-set" | "domain-endpoint-clear" | "domain-delegate-set" | "domain-delegate-clear" | "domain-miner-set" | "domain-miner-clear" | "domain-canonical" | "field-list" | "field-show" | "field-create" | "field-set" | "field-clear" | "send" | "claim" | "reclaim" | "cog-send" | "cog-claim" | "cog-reclaim" | "cog-lock" | "rep-give" | "rep-revoke" | "cog-balance" | "cog-locks" | "mine" | "mine-start" | "mine-stop" | "mine-setup" | "mine-status" | "mine-log" | "wallet-init" | "wallet-delete" | "wallet-restore" | "wallet-show-mnemonic" | "wallet-status" | "wallet-address" | "wallet-ids" | "address" | "ids" | "balance" | "locks" | "domain-list" | "domains" | "domain-show" | "show" | "fields" | "field";
+export type CommandName = "init" | "restore" | "reset" | "repair" | "update" | "sync" | "status" | "client-lock" | "client-change-password" | "client-unlock" | "follow" | "bitcoin-start" | "bitcoin-stop" | "bitcoin-status" | "bitcoin-transfer" | "indexer-start" | "indexer-stop" | "indexer-status" | "anchor" | "domain-anchor" | "register" | "domain-register" | "transfer" | "domain-transfer" | "sell" | "domain-sell" | "unsell" | "domain-unsell" | "buy" | "domain-buy" | "domain-endpoint-set" | "domain-endpoint-clear" | "domain-delegate-set" | "domain-delegate-clear" | "domain-miner-set" | "domain-miner-clear" | "domain-canonical" | "field-list" | "field-show" | "field-create" | "field-set" | "field-clear" | "send" | "claim" | "reclaim" | "cog-send" | "cog-claim" | "cog-reclaim" | "cog-lock" | "rep-give" | "rep-revoke" | "cog-balance" | "cog-locks" | "mine" | "mine-start" | "mine-stop" | "mine-setup" | "mine-status" | "mine-log" | "wallet-init" | "wallet-delete" | "wallet-restore" | "wallet-show-mnemonic" | "wallet-status" | "wallet-address" | "wallet-ids" | "address" | "ids" | "balance" | "locks" | "domain-list" | "domains" | "domain-show" | "show" | "fields" | "field";
 export interface WritableLike {
     isTTY?: boolean;
     write(chunk: string): void;
@@ -92,6 +92,11 @@ export interface CliRunnerContext {
     signalSource?: SignalSource;
     forceExit?: (code: number) => never | void;
     fetchImpl?: typeof fetch;
+    runGlobalClientUpdateInstall?: (options: {
+        stdout: WritableLike;
+        stderr: WritableLike;
+        env: NodeJS.ProcessEnv;
+    }) => Promise<void>;
     openSqliteStore?: typeof openSqliteStore;
     openManagedBitcoindClient?: (options: {
         store: ClientStoreAdapter;

package/dist/cli/update-notifier.js

@@ -1,143 +1,14 @@
-import { readFile } from "node:fs/promises";
-import { writeJsonFileAtomic } from "../wallet/fs/atomic.js";
 import { writeLine } from "./io.js";
-const UPDATE_CHECK_CACHE_SCHEMA_VERSION = 1;
-const UPDATE_CHECK_MAX_AGE_MS = 24 * 60 * 60 * 1000;
-const UPDATE_CHECK_TIMEOUT_MS = 500;
-const UPDATE_CHECK_URL = "https://registry.npmjs.org/@cogcoin/client/latest";
-function createEmptyUpdateCheckCache() {
-    return {
-        schemaVersion: UPDATE_CHECK_CACHE_SCHEMA_VERSION,
-        lastCheckedAtUnixMs: 0,
-        latestVersion: null,
-        lastNotifiedCurrentVersion: null,
-        lastNotifiedLatestVersion: null,
-        lastNotifiedAtUnixMs: null,
-    };
-}
-function parseSemver(version) {
-    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(version.trim());
-    if (match === null) {
-        return null;
-    }
-    const prerelease = match[4] === undefined
-        ? []
-        : match[4].split(".").map((raw) => ({
-            raw,
-            numeric: /^(0|[1-9]\d*)$/.test(raw),
-            numericValue: /^(0|[1-9]\d*)$/.test(raw) ? Number(raw) : null,
-        }));
-    return {
-        major: Number(match[1]),
-        minor: Number(match[2]),
-        patch: Number(match[3]),
-        prerelease,
-    };
-}
-function compareSemver(left, right) {
-    const leftParsed = parseSemver(left);
-    const rightParsed = parseSemver(right);
-    if (leftParsed === null || rightParsed === null) {
-        return null;
-    }
-    if (leftParsed.major !== rightParsed.major) {
-        return leftParsed.major > rightParsed.major ? 1 : -1;
-    }
-    if (leftParsed.minor !== rightParsed.minor) {
-        return leftParsed.minor > rightParsed.minor ? 1 : -1;
-    }
-    if (leftParsed.patch !== rightParsed.patch) {
-        return leftParsed.patch > rightParsed.patch ? 1 : -1;
-    }
-    if (leftParsed.prerelease.length === 0 && rightParsed.prerelease.length === 0) {
-        return 0;
-    }
-    if (leftParsed.prerelease.length === 0) {
-        return 1;
-    }
-    if (rightParsed.prerelease.length === 0) {
-        return -1;
-    }
-    const maxLength = Math.max(leftParsed.prerelease.length, rightParsed.prerelease.length);
-    for (let index = 0; index < maxLength; index += 1) {
-        const leftIdentifier = leftParsed.prerelease[index];
-        const rightIdentifier = rightParsed.prerelease[index];
-        if (leftIdentifier === undefined) {
-            return -1;
-        }
-        if (rightIdentifier === undefined) {
-            return 1;
-        }
-        if (leftIdentifier.numeric && rightIdentifier.numeric) {
-            if (leftIdentifier.numericValue !== rightIdentifier.numericValue) {
-                return leftIdentifier.numericValue > rightIdentifier.numericValue ? 1 : -1;
-            }
-            continue;
-        }
-        if (leftIdentifier.numeric !== rightIdentifier.numeric) {
-            return leftIdentifier.numeric ? -1 : 1;
-        }
-        if (leftIdentifier.raw !== rightIdentifier.raw) {
-            return leftIdentifier.raw > rightIdentifier.raw ? 1 : -1;
-        }
-    }
-    return 0;
-}
-function isUpdateCheckDisabled(env) {
-    const raw = env.COGCOIN_DISABLE_UPDATE_CHECK;
-    if (raw === undefined) {
+import { PASSIVE_UPDATE_CHECK_TIMEOUT_MS, UPDATE_CHECK_MAX_AGE_MS, applyUpdateCheckResult, compareSemver, createEmptyUpdateCheckCache, fetchLatestPublishedVersion, isUpdateCheckDisabled, loadUpdateCheckCache, persistUpdateCheckCache, recordUpdateNotification, shouldRefreshUpdateCheck, } from "./update-service.js";
+function isEligibleForUpdateNotification(parsed, context) {
+    if (parsed.command === "update") {
         return false;
     }
-    const normalized = raw.trim().toLowerCase();
-    return normalized === "1" || normalized === "true" || normalized === "yes";
-}
-function isEligibleForUpdateNotification(parsed, context) {
     if (parsed.outputMode !== "text" || parsed.help || parsed.version) {
         return false;
     }
     return context.stdout.isTTY === true || context.stderr.isTTY === true;
 }
-function normalizeUpdateCheckCache(parsed) {
-    if (typeof parsed !== "object" || parsed === null) {
-        return null;
-    }
-    const candidate = parsed;
-    if (candidate.schemaVersion !== UPDATE_CHECK_CACHE_SCHEMA_VERSION) {
-        return null;
-    }
-    return {
-        schemaVersion: UPDATE_CHECK_CACHE_SCHEMA_VERSION,
-        lastCheckedAtUnixMs: typeof candidate.lastCheckedAtUnixMs === "number" ? candidate.lastCheckedAtUnixMs : 0,
-        latestVersion: typeof candidate.latestVersion === "string" ? candidate.latestVersion : null,
-        lastNotifiedCurrentVersion: typeof candidate.lastNotifiedCurrentVersion === "string"
-            ? candidate.lastNotifiedCurrentVersion
-            : null,
-        lastNotifiedLatestVersion: typeof candidate.lastNotifiedLatestVersion === "string"
-            ? candidate.lastNotifiedLatestVersion
-            : null,
-        lastNotifiedAtUnixMs: typeof candidate.lastNotifiedAtUnixMs === "number"
-            ? candidate.lastNotifiedAtUnixMs
-            : null,
-        lastCheckErrorKind: typeof candidate.lastCheckErrorKind === "string"
-            ? candidate.lastCheckErrorKind
-            : undefined,
-    };
-}
-async function loadUpdateCheckCache(cachePath) {
-    try {
-        const raw = await readFile(cachePath, "utf8");
-        return normalizeUpdateCheckCache(JSON.parse(raw));
-    }
-    catch (error) {
-        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-            return null;
-        }
-        return null;
-    }
-}
-function shouldRefreshUpdateCheck(cache, now) {
-    return now - cache.lastCheckedAtUnixMs >= UPDATE_CHECK_MAX_AGE_MS;
-}
 function shouldNotifyForVersionPair(cache, currentVersion, latestVersion, now) {
     const versionComparison = compareSemver(latestVersion, currentVersion);
     if (versionComparison === null || versionComparison <= 0) {
@@ -152,117 +23,31 @@ function shouldNotifyForVersionPair(cache, currentVersion, latestVersion, now) {
     }
     return now - cache.lastNotifiedAtUnixMs >= UPDATE_CHECK_MAX_AGE_MS;
 }
-function recordUpdateNotification(cache, currentVersion, latestVersion, now) {
-    return {
-        ...cache,
-        lastNotifiedCurrentVersion: currentVersion,
-        lastNotifiedLatestVersion: latestVersion,
-        lastNotifiedAtUnixMs: now,
-    };
-}
-async function fetchLatestPublishedVersion(fetchImpl) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => {
-        controller.abort();
-    }, UPDATE_CHECK_TIMEOUT_MS);
-    try {
-        const response = await fetchImpl(UPDATE_CHECK_URL, {
-            headers: {
-                accept: "application/json",
-            },
-            signal: controller.signal,
-        });
-        if (!response.ok) {
-            return {
-                kind: "failure",
-                errorKind: `http_${response.status}`,
-            };
-        }
-        let payload;
-        try {
-            payload = await response.json();
-        }
-        catch {
-            return {
-                kind: "failure",
-                errorKind: "invalid_json",
-            };
-        }
-        const latestVersion = typeof payload.version === "string"
-            ? payload.version
-            : null;
-        if (latestVersion === null) {
-            return {
-                kind: "failure",
-                errorKind: "invalid_payload",
-            };
-        }
-        if (parseSemver(latestVersion) === null) {
-            return {
-                kind: "failure",
-                errorKind: "invalid_semver",
-            };
-        }
-        return {
-            kind: "success",
-            latestVersion,
-        };
-    }
-    catch (error) {
-        if (error instanceof Error && error.name === "AbortError") {
-            return {
-                kind: "failure",
-                errorKind: "timeout",
-            };
-        }
-        return {
-            kind: "failure",
-            errorKind: "network",
-        };
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
 function writeUpdateNotice(context, currentVersion, latestVersion) {
     writeLine(context.stderr, `Update available: Cogcoin ${currentVersion} -> ${latestVersion}`);
     writeLine(context.stderr, "Run: npm install -g @cogcoin/client");
 }
-async function persistUpdateCheckCache(cachePath, cache) {
-    await writeJsonFileAtomic(cachePath, cache);
-}
 export async function maybeNotifyAboutCliUpdate(parsed, context) {
     try {
         if (!isEligibleForUpdateNotification(parsed, context) || isUpdateCheckDisabled(context.env)) {
             return;
         }
         const currentVersion = await context.readPackageVersion();
-        if (parseSemver(currentVersion) === null) {
-            return;
-        }
         const cachePath = context.resolveUpdateCheckStatePath();
         const now = context.now();
         let cache = await loadUpdateCheckCache(cachePath) ?? createEmptyUpdateCheckCache();
         let cacheChanged = false;
         if (shouldRefreshUpdateCheck(cache, now)) {
-            const updateResult = await fetchLatestPublishedVersion(context.fetchImpl);
-            cache = {
-                ...cache,
-                lastCheckedAtUnixMs: now,
-                latestVersion: updateResult.kind === "success"
-                    ? updateResult.latestVersion
-                    : cache.latestVersion,
-                lastCheckErrorKind: updateResult.kind === "success"
-                    ? undefined
-                    : updateResult.errorKind,
-            };
+            const updateResult = await fetchLatestPublishedVersion(context.fetchImpl, {
+                timeoutMs: PASSIVE_UPDATE_CHECK_TIMEOUT_MS,
+            });
+            cache = applyUpdateCheckResult(cache, updateResult, now);
             cacheChanged = true;
         }
         if (cache.latestVersion !== null
             && shouldNotifyForVersionPair(cache, currentVersion, cache.latestVersion, now)) {
             writeUpdateNotice(context, currentVersion, cache.latestVersion);
             cache = recordUpdateNotification(cache, currentVersion, cache.latestVersion, now);
-            cacheChanged = true;
             await persistUpdateCheckCache(cachePath, cache);
             return;
         }

package/dist/cli/update-service.d.ts

@@ -0,0 +1,44 @@
+export declare const UPDATE_CHECK_CACHE_SCHEMA_VERSION = 1;
+export declare const UPDATE_CHECK_MAX_AGE_MS: number;
+export declare const PASSIVE_UPDATE_CHECK_TIMEOUT_MS = 500;
+export declare const EXPLICIT_UPDATE_CHECK_TIMEOUT_MS = 5000;
+export declare const UPDATE_CHECK_URL = "https://registry.npmjs.org/@cogcoin/client/latest";
+export declare const CLI_INSTALL_COMMAND = "npm install -g @cogcoin/client";
+export interface ParsedSemver {
+    major: number;
+    minor: number;
+    patch: number;
+    prerelease: Array<{
+        raw: string;
+        numeric: boolean;
+        numericValue: number | null;
+    }>;
+}
+export interface UpdateCheckCache {
+    schemaVersion: typeof UPDATE_CHECK_CACHE_SCHEMA_VERSION;
+    lastCheckedAtUnixMs: number;
+    latestVersion: string | null;
+    lastNotifiedCurrentVersion: string | null;
+    lastNotifiedLatestVersion: string | null;
+    lastNotifiedAtUnixMs: number | null;
+    lastCheckErrorKind?: string;
+}
+export type UpdateCheckResult = {
+    kind: "success";
+    latestVersion: string;
+} | {
+    kind: "failure";
+    errorKind: string;
+};
+export declare function createEmptyUpdateCheckCache(): UpdateCheckCache;
+export declare function parseSemver(version: string): ParsedSemver | null;
+export declare function compareSemver(left: string, right: string): number | null;
+export declare function isUpdateCheckDisabled(env: NodeJS.ProcessEnv): boolean;
+export declare function loadUpdateCheckCache(cachePath: string): Promise<UpdateCheckCache | null>;
+export declare function shouldRefreshUpdateCheck(cache: UpdateCheckCache, now: number): boolean;
+export declare function applyUpdateCheckResult(cache: UpdateCheckCache, result: UpdateCheckResult, now: number): UpdateCheckCache;
+export declare function recordUpdateNotification(cache: UpdateCheckCache, currentVersion: string, latestVersion: string, now: number): UpdateCheckCache;
+export declare function fetchLatestPublishedVersion(fetchImpl: typeof fetch, options?: {
+    timeoutMs?: number;
+}): Promise<UpdateCheckResult>;
+export declare function persistUpdateCheckCache(cachePath: string, cache: UpdateCheckCache): Promise<void>;