import type { EnvironmentName } from '../config/environments.js';
import { type UpdateCheckCache, type UpdateTag } from './notice.js';
export declare function updateCachePath(baseDir?: string): string;
/**
 * The last recorded answer, or null if there is none to trust.
 *
 * Missing, unreadable and malformed all collapse to null on purpose: the caller's next move is
 * identical in every case — say nothing now, refresh in the background — and this is a hint, not
 * a thing worth failing a command over.
 */
export declare function readUpdateCache(baseDir?: string): UpdateCheckCache | null;
export declare function writeUpdateCache(cache: UpdateCheckCache, baseDir?: string): void;
/**
 * Ask npm what the newest version published under `tag` is. Null on any failure.
 *
 * Per-tag rather than always `latest`, so a build installed from the dev line is told about the
 * next dev build instead of about a production release it deliberately runs ahead of.
 */
export declare function fetchTagVersion(tag: UpdateTag, fetchImpl?: typeof globalThis.fetch): Promise<string | null>;
/**
 * The notice to print right now, decided entirely from the cache.
 *
 * Nothing here awaits the network. A stale cache is refreshed by `refreshUpdateCacheInBackground`
 * for the NEXT run, which is why a first-ever invocation is silent — the alternative is making
 * every command wait on npm to be told something it could just as well be told tomorrow.
 */
export declare function pendingUpdateNotice(currentVersion: string, baseDir?: string): string | null;
/**
 * The single line bin.ts prints before a command runs — at most one install command, ever.
 *
 * The wrong-line notice wins over the newer-version one, and suppresses it. Both at once would
 * print two different `npm i -g` commands in the same breath ("update to 0.1.45 on your line" next
 * to "be on the other line"), which is the ambiguity this exists to end: a creator standing in a
 * project should never have to choose which one they meant.
 *
 * `projectEnvironment` is the project's committed pin, or undefined outside a project and for one
 * that has none. Undefined leaves the old behaviour exactly as it was: nothing here invents a line
 * for a directory that never claimed one.
 */
export declare function startupNotice(currentVersion: string, projectEnvironment: EnvironmentName | undefined, baseDir?: string): string | null;
/**
 * Refresh the cache if it is stale. Fire-and-forget: callers must not await this.
 *
 * Returns a promise only so tests can. In production the process may well exit first, which is
 * fine — the next run reads whatever was written, and an unwritten cache simply stays stale.
 */
export declare function refreshUpdateCacheInBackground(currentVersion: string, now?: number, baseDir?: string, fetchImpl?: typeof globalThis.fetch): Promise<void>;