@cogcoin/client 1.0.0 → 1.0.2

package/dist/cli/sync-progress.js

@@ -0,0 +1,91 @@
+import { formatBytes, formatDuration } from "../bitcoind/progress/formatting.js";
+const SYNC_PROGRESS_LOG_INTERVAL_MS = 5_000;
+export function createSyncProgressReporter(options) {
+    let lastPhase = null;
+    let lastMessage = "";
+    let lastDownloadPrintedAt = 0;
+    let lastDownloadBytes = null;
+    let lastImportPrintedAt = 0;
+    let lastImportBlocks = null;
+    const infoEnabled = options.progressOutput !== "none";
+    function shouldPrintEntryMessage(message, phase) {
+        if (message === "Waiting to start managed sync." || message === "Sync complete.") {
+            return false;
+        }
+        if (message.startsWith("Warning:")) {
+            return true;
+        }
+        if (!infoEnabled) {
+            return false;
+        }
+        if (phase === "getblock_archive_download" || phase === "getblock_archive_import") {
+            return true;
+        }
+        return phase === "snapshot_download"
+            || phase === "wait_headers_for_snapshot"
+            || phase === "load_snapshot"
+            || phase === "bitcoin_sync"
+            || phase === "cogcoin_sync"
+            || message.includes("Getblock manifest")
+            || message.startsWith("Fetching Getblock manifest.")
+            || message.startsWith("Refreshing Getblock manifest.")
+            || message.startsWith("Using Getblock range ");
+    }
+    function formatDownloadLine(label, event) {
+        const current = event.progress.downloadedBytes ?? 0;
+        const total = event.progress.totalBytes ?? 0;
+        const percent = event.progress.percent ?? (total > 0 ? (current / total) * 100 : 0);
+        const speed = event.progress.bytesPerSecond === null ? "--" : `${formatBytes(event.progress.bytesPerSecond)}/s`;
+        return `${label}: ${percent.toFixed(2)}% (${formatBytes(current)} / ${formatBytes(total)}, ${speed}, ETA ${formatDuration(event.progress.etaSeconds)})`;
+    }
+    return (event) => {
+        const message = event.progress.message.trim();
+        const phaseChanged = event.phase !== lastPhase;
+        const messageChanged = message !== lastMessage;
+        if ((phaseChanged || messageChanged) && shouldPrintEntryMessage(message, event.phase)) {
+            options.write(message);
+        }
+        if (infoEnabled && event.phase === "getblock_archive_download") {
+            const now = Date.now();
+            const currentBytes = event.progress.downloadedBytes ?? 0;
+            const isComplete = (event.progress.percent ?? 0) >= 100;
+            const shouldPrintMilestone = phaseChanged
+                || lastDownloadBytes !== currentBytes && (isComplete
+                    || now - lastDownloadPrintedAt >= SYNC_PROGRESS_LOG_INTERVAL_MS);
+            if (shouldPrintMilestone) {
+                options.write(formatDownloadLine("Getblock download", event));
+                lastDownloadPrintedAt = now;
+                lastDownloadBytes = currentBytes;
+            }
+        }
+        else if (infoEnabled && event.phase === "snapshot_download") {
+            const now = Date.now();
+            const currentBytes = event.progress.downloadedBytes ?? 0;
+            const isComplete = (event.progress.percent ?? 0) >= 100;
+            const shouldPrintMilestone = phaseChanged
+                || lastDownloadBytes !== currentBytes && (isComplete
+                    || now - lastDownloadPrintedAt >= SYNC_PROGRESS_LOG_INTERVAL_MS);
+            if (shouldPrintMilestone) {
+                options.write(formatDownloadLine("Snapshot download", event));
+                lastDownloadPrintedAt = now;
+                lastDownloadBytes = currentBytes;
+            }
+        }
+        else if (infoEnabled && event.phase === "getblock_archive_import") {
+            const now = Date.now();
+            const currentBlocks = event.progress.blocks ?? 0;
+            const targetBlocks = event.progress.targetHeight ?? currentBlocks;
+            const isComplete = currentBlocks >= targetBlocks;
+            const shouldPrintMilestone = phaseChanged
+                || lastImportBlocks !== currentBlocks && (isComplete
+                    || now - lastImportPrintedAt >= SYNC_PROGRESS_LOG_INTERVAL_MS);
+            if (shouldPrintMilestone) {
+                options.write(`Getblock import: Bitcoin ${currentBlocks.toLocaleString()} / ${targetBlocks.toLocaleString()}`);
+                lastImportPrintedAt = now;
+                lastImportBlocks = currentBlocks;
+            }
+        }
+        lastPhase = event.phase;
+        lastMessage = message;
+    };
+}

package/dist/cli/types.d.ts

@@ -10,11 +10,11 @@ import type { WalletPrompter, initializeWallet, deleteImportedWalletSeed, previe
 import type { openWalletReadContext } from "../wallet/read/index.js";
 import { loadRawWalletStateEnvelope, loadWalletState } from "../wallet/state/storage.js";
 import type { WalletSecretProvider } from "../wallet/state/provider.js";
-import type { followMiningLog, inspectMiningControlPlane, readMiningLog, runForegroundMining, setupBuiltInMining, startBackgroundMining, stopBackgroundMining } from "../wallet/mining/index.js";
+import type { ensureBuiltInMiningSetupIfNeeded, followMiningLog, inspectMiningControlPlane, readMiningLog, runForegroundMining, setupBuiltInMining, startBackgroundMining, stopBackgroundMining } from "../wallet/mining/index.js";
 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;
@@ -145,6 +150,7 @@ export interface CliRunnerContext {
     giveReputation?: typeof giveReputation;
     revokeReputation?: typeof revokeReputation;
     inspectMiningControlPlane?: typeof inspectMiningControlPlane;
+    ensureBuiltInMiningSetupIfNeeded?: typeof ensureBuiltInMiningSetupIfNeeded;
     runForegroundMining?: typeof runForegroundMining;
     startBackgroundMining?: typeof startBackgroundMining;
     stopBackgroundMining?: typeof stopBackgroundMining;

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>;

package/dist/cli/update-service.js

@@ -0,0 +1,218 @@
+import { readFile } from "node:fs/promises";
+import { writeJsonFileAtomic } from "../wallet/fs/atomic.js";
+export const UPDATE_CHECK_CACHE_SCHEMA_VERSION = 1;
+export const UPDATE_CHECK_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+export const PASSIVE_UPDATE_CHECK_TIMEOUT_MS = 500;
+export const EXPLICIT_UPDATE_CHECK_TIMEOUT_MS = 5_000;
+export const UPDATE_CHECK_URL = "https://registry.npmjs.org/@cogcoin/client/latest";
+export const CLI_INSTALL_COMMAND = "npm install -g @cogcoin/client";
+export function createEmptyUpdateCheckCache() {
+    return {
+        schemaVersion: UPDATE_CHECK_CACHE_SCHEMA_VERSION,
+        lastCheckedAtUnixMs: 0,
+        latestVersion: null,
+        lastNotifiedCurrentVersion: null,
+        lastNotifiedLatestVersion: null,
+        lastNotifiedAtUnixMs: null,
+    };
+}
+export 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,
+    };
+}
+export 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;
+}
+export function isUpdateCheckDisabled(env) {
+    const raw = env.COGCOIN_DISABLE_UPDATE_CHECK;
+    if (raw === undefined) {
+        return false;
+    }
+    const normalized = raw.trim().toLowerCase();
+    return normalized === "1" || normalized === "true" || normalized === "yes";
+}
+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,
+    };
+}
+export 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;
+    }
+}
+export function shouldRefreshUpdateCheck(cache, now) {
+    return now - cache.lastCheckedAtUnixMs >= UPDATE_CHECK_MAX_AGE_MS;
+}
+export function applyUpdateCheckResult(cache, result, now) {
+    return {
+        ...cache,
+        lastCheckedAtUnixMs: now,
+        latestVersion: result.kind === "success" ? result.latestVersion : cache.latestVersion,
+        lastCheckErrorKind: result.kind === "success" ? undefined : result.errorKind,
+    };
+}
+export function recordUpdateNotification(cache, currentVersion, latestVersion, now) {
+    return {
+        ...cache,
+        lastNotifiedCurrentVersion: currentVersion,
+        lastNotifiedLatestVersion: latestVersion,
+        lastNotifiedAtUnixMs: now,
+    };
+}
+export async function fetchLatestPublishedVersion(fetchImpl, options = {}) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+        controller.abort();
+    }, options.timeoutMs ?? PASSIVE_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);
+    }
+}
+export async function persistUpdateCheckCache(cachePath, cache) {
+    await writeJsonFileAtomic(cachePath, cache);
+}

package/dist/cli/wallet-format.js

@@ -558,6 +558,9 @@ function getBalanceNextSteps(context) {
             return [`Transfer BTC to ${context.model.walletAddress ?? "this wallet address"} so your anchored root domain can keep mining.`];
         }
         if (context.fundingSpendableSats !== null && context.fundingSpendableSats > BALANCE_MINING_THRESHOLD_SATS) {
+            if (context.mining?.provider.status === "missing") {
+                return ["Run `cogcoin mine setup` to configure your mining provider."];
+            }
             return ["Run `cogcoin mine` to start mining with your anchored root domain."];
         }
         return [];