@cogcoin/client 1.0.1 → 1.1.0

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,14 @@ 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.currentPublishDecision === "publish-paused-insufficient-funds") {
+        nextSteps.push("Wait for enough safe BTC funding to become spendable for the next publish; mining resumes automatically.");
+    }
     else if (mining.runtime.pauseReason === "zero-reward") {
         nextSteps.push("Wait for the next positive-reward target height; mining resumes automatically.");
     }
@@ -472,6 +492,34 @@ export function buildMineLogJson(events, page, rotation) {
         },
     };
 }
+export function buildMinePromptListJson(result) {
+    const explanations = [];
+    const nextSteps = [];
+    if (result.prompts.length === 0) {
+        explanations.push("No mineable root domains or stored per-domain mining prompts are configured.");
+        nextSteps.push("Run `cogcoin domains --mineable` to see eligible mining domains.");
+    }
+    else {
+        const nextDomainPrompt = result.prompts.find((entry) => entry.mineable && entry.prompt === null);
+        if (nextDomainPrompt !== undefined) {
+            nextSteps.push(`cogcoin mine prompt ${nextDomainPrompt.domain.name}`);
+        }
+    }
+    return {
+        warnings: [],
+        explanations,
+        nextSteps,
+        data: {
+            fallbackPromptConfigured: result.fallbackPromptConfigured,
+            prompts: result.prompts.map((entry) => ({
+                domain: entry.domain,
+                mineable: entry.mineable,
+                prompt: entry.prompt,
+                effectivePromptSource: entry.effectivePromptSource,
+            })),
+        },
+    };
+}
 export function buildBalanceJson(context) {
     const messages = createBaseMessages(context);
     const total = walletCogBalance(context);

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({
@@ -88,7 +92,8 @@ export async function runCli(argv, contextOverrides = {}) {
             || parsed.command === "mine-stop") {
             return runMiningRuntimeCommand(parsed, context);
         }
-        if (parsed.command === "mine-setup") {
+        if (parsed.command === "mine-setup"
+            || parsed.command === "mine-prompt") {
             return runMiningAdminCommand(parsed, context);
         }
         if (parsed.command === "init"
@@ -135,7 +140,8 @@ export async function runCli(argv, contextOverrides = {}) {
             || parsed.command === "rep-revoke") {
             return runWalletMutationCommand(parsed, context);
         }
-        if (parsed.command === "mine-status"
+        if (parsed.command === "mine-prompt-list"
+            || parsed.command === "mine-status"
             || parsed.command === "mine-log") {
             return runMiningReadCommand(parsed, context);
         }

package/dist/cli/signals.d.ts

@@ -1,4 +1,16 @@
 import type { InterruptibleOutcome, ManagedClientLike, SignalSource, StopSignalWatcher, WritableLike } from "./types.js";
+export declare function createCloseSignalWatcher(options: {
+    signalSource: SignalSource;
+    stderr: WritableLike;
+    closeable: {
+        close(): Promise<void>;
+    };
+    forceExit: (code: number) => never | void;
+    lockPaths?: readonly string[];
+    firstMessage?: string | null;
+    successMessage?: string | null;
+    failureMessage?: string | null;
+}): StopSignalWatcher;
 export declare function createStopSignalWatcher(signalSource: SignalSource, stderr: WritableLike, client: ManagedClientLike, forceExit: (code: number) => never | void, lockPaths?: readonly string[]): StopSignalWatcher;
 export declare function createOwnedLockCleanupSignalWatcher(signalSource: SignalSource, forceExit: (code: number) => never | void, lockPaths: readonly string[]): StopSignalWatcher;
 export declare function waitForCompletionOrStop<T>(promise: Promise<T>, stopWatcher: StopSignalWatcher): Promise<InterruptibleOutcome<T>>;

package/dist/cli/signals.js

@@ -1,12 +1,12 @@
 import { writeLine } from "./io.js";
 import { clearLockIfOwnedByCurrentProcess } from "../wallet/fs/lock.js";
-export function createStopSignalWatcher(signalSource, stderr, client, forceExit, lockPaths = []) {
+export function createCloseSignalWatcher(options) {
     let closing = false;
     let resolved = false;
     let onSignal = () => { };
     const cleanup = () => {
-        signalSource.off("SIGINT", onSignal);
-        signalSource.off("SIGTERM", onSignal);
+        options.signalSource.off("SIGINT", onSignal);
+        options.signalSource.off("SIGTERM", onSignal);
     };
     const promise = new Promise((resolve) => {
         const settle = (code) => {
@@ -18,26 +18,32 @@ export function createStopSignalWatcher(signalSource, stderr, client, forceExit,
             resolve(code);
         };
         const releaseOwnedLocks = async () => {
-            await Promise.allSettled([...new Set(lockPaths)].map(async (lockPath) => {
+            await Promise.allSettled([...new Set(options.lockPaths ?? [])].map(async (lockPath) => {
                 await clearLockIfOwnedByCurrentProcess(lockPath);
             }));
         };
         const onFirstSignal = () => {
             closing = true;
-            writeLine(stderr, "Detaching from managed Cogcoin client and resuming background indexer follow...");
-            void client.close().then(async () => {
+            if (options.firstMessage !== null && options.firstMessage !== undefined) {
+                writeLine(options.stderr, options.firstMessage);
+            }
+            void options.closeable.close().then(async () => {
                 await releaseOwnedLocks();
                 if (resolved) {
                     return;
                 }
-                writeLine(stderr, "Detached cleanly; background indexer follow resumed.");
+                if (options.successMessage !== null && options.successMessage !== undefined) {
+                    writeLine(options.stderr, options.successMessage);
+                }
                 settle(0);
             }, async () => {
                 await releaseOwnedLocks();
                 if (resolved) {
                     return;
                 }
-                writeLine(stderr, "Detach failed before background indexer follow was confirmed.");
+                if (options.failureMessage !== null && options.failureMessage !== undefined) {
+                    writeLine(options.stderr, options.failureMessage);
+                }
                 settle(1);
             });
         };
@@ -47,23 +53,35 @@ export function createStopSignalWatcher(signalSource, stderr, client, forceExit,
                 return;
             }
             settle(130);
-            if (lockPaths.length === 0) {
-                forceExit(130);
+            if ((options.lockPaths ?? []).length === 0) {
+                options.forceExit(130);
                 return;
             }
             void releaseOwnedLocks().finally(() => {
-                forceExit(130);
+                options.forceExit(130);
             });
         };
     });
-    signalSource.on("SIGINT", onSignal);
-    signalSource.on("SIGTERM", onSignal);
+    options.signalSource.on("SIGINT", onSignal);
+    options.signalSource.on("SIGTERM", onSignal);
     return {
         cleanup,
         isStopping: () => closing,
         promise,
     };
 }
+export function createStopSignalWatcher(signalSource, stderr, client, forceExit, lockPaths = []) {
+    return createCloseSignalWatcher({
+        signalSource,
+        stderr,
+        closeable: client,
+        forceExit,
+        lockPaths,
+        firstMessage: "Detaching from managed Cogcoin client and resuming background indexer follow...",
+        successMessage: "Detached cleanly; background indexer follow resumed.",
+        failureMessage: "Detach failed before background indexer follow was confirmed.",
+    });
+}
 export function createOwnedLockCleanupSignalWatcher(signalSource, forceExit, lockPaths) {
     let stopping = false;
     let resolved = false;

package/dist/cli/types.d.ts

@@ -1,4 +1,5 @@
 import type { inspectPassiveClientStatus } from "../passive-status.js";
+import type { ManagedIndexerMonitor, openManagedIndexerMonitor } from "../bitcoind/indexer-monitor.js";
 import { createRpcClient } from "../bitcoind/node.js";
 import type { ManagedBitcoindProgressEvent } from "../bitcoind/types.js";
 import { attachOrStartIndexerDaemon, probeIndexerDaemon, readObservedIndexerDaemonStatus, stopIndexerDaemonService } from "../bitcoind/indexer-daemon.js";
@@ -10,11 +11,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 { ensureBuiltInMiningSetupIfNeeded, followMiningLog, inspectMiningControlPlane, readMiningLog, runForegroundMining, setupBuiltInMining, startBackgroundMining, stopBackgroundMining } from "../wallet/mining/index.js";
+import type { ensureBuiltInMiningSetupIfNeeded, followMiningLog, inspectMiningControlPlane, inspectMiningDomainPromptState, readMiningLog, runForegroundMining, setupBuiltInMining, startBackgroundMining, stopBackgroundMining, updateMiningDomainPrompt } 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-prompt" | "mine-prompt-list" | "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;
@@ -71,7 +72,6 @@ export interface ManagedClientLike {
         bestHeight: number;
     }>;
     playSyncCompletionScene?(): Promise<void>;
-    detachToBackgroundFollow?(): Promise<void>;
     startFollowingTip(): Promise<void>;
     getNodeStatus(): Promise<{
         indexedTip: {
@@ -83,6 +83,8 @@ export interface ManagedClientLike {
     }>;
     close(): Promise<void>;
 }
+export interface ManagedIndexerMonitorLike extends ManagedIndexerMonitor {
+}
 export interface CliRunnerContext {
     stdout?: WritableLike;
     stderr?: WritableLike;
@@ -92,10 +94,14 @@ 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;
-        databasePath?: string;
         dataDir?: string;
         walletRootId?: string;
         progressOutput?: ProgressOutput;
@@ -105,6 +111,7 @@ export interface CliRunnerContext {
             nextArchiveEndHeight: number;
         }) => Promise<boolean>;
     }) => Promise<ManagedClientLike>;
+    openManagedIndexerMonitor?: typeof openManagedIndexerMonitor;
     attachManagedBitcoindService?: typeof attachOrStartManagedBitcoindService;
     probeManagedBitcoindService?: typeof probeManagedBitcoindService;
     stopManagedBitcoindService?: typeof stopManagedBitcoindService;
@@ -145,11 +152,13 @@ export interface CliRunnerContext {
     giveReputation?: typeof giveReputation;
     revokeReputation?: typeof revokeReputation;
     inspectMiningControlPlane?: typeof inspectMiningControlPlane;
+    inspectMiningDomainPromptState?: typeof inspectMiningDomainPromptState;
     ensureBuiltInMiningSetupIfNeeded?: typeof ensureBuiltInMiningSetupIfNeeded;
     runForegroundMining?: typeof runForegroundMining;
     startBackgroundMining?: typeof startBackgroundMining;
     stopBackgroundMining?: typeof stopBackgroundMining;
     setupBuiltInMining?: typeof setupBuiltInMining;
+    updateMiningDomainPrompt?: typeof updateMiningDomainPrompt;
     readMiningLog?: typeof readMiningLog;
     followMiningLog?: typeof followMiningLog;
     repairWallet?: typeof repairWallet;

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,34 @@
+import { compareSemver, parseSemver, type ParsedSemver } from "../semver.js";
+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 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 { compareSemver, parseSemver, type ParsedSemver };
+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>;