fix(smartupdate): improve update check caching, validation, and error handling

ts/smartupdate.interfaces.ts

@@ -1,12 +1,19 @@
 import type { TLogLevel } from './smartupdate.constants.js';
 import type * as smartnpm from '@push.rocks/smartnpm';
 
+export type TCacheStrategy = 'always' | 'never' | 'time-based';
+export type TCacheStoreType = 'custom' | 'userHomeDir' | 'ephemeral';
+export type TCachedUpdateStatus = 'up-to-date' | 'update-available';
+
 /**
  * Cache status stored for each package
  */
 export interface ICacheStatus {
   lastCheck: number;
   latestVersion: string;
+  currentVersion?: string;
+  registryUrl?: string;
+  status?: TCachedUpdateStatus;
   performedUpgrade: boolean;
 }
 
@@ -46,6 +53,16 @@ export interface ISmartUpdateOptions {
    * @default false
    */
   noColor?: boolean;
+
+  /**
+   * Cache storage configuration
+   * @default { storeType: 'userHomeDir', storeIdentifier: 'global_smartupdate' }
+   */
+  cacheStore?: {
+    storeType?: TCacheStoreType;
+    storeIdentifier?: string;
+    customPath?: string;
+  };
 }
 
 /**
@@ -77,12 +94,12 @@ export interface IUpdateCheckOptions {
 
   /**
    * Cache strategy for this check
-   * - 'always': Always check cache first (default for CLI)
+   * - 'always': Always use an existing matching cache entry
    * - 'never': Always check registry, bypass cache
    * - 'time-based': Check based on cache duration
    * @default 'time-based'
    */
-  cacheStrategy?: 'always' | 'never' | 'time-based';
+  cacheStrategy?: TCacheStrategy;
 }
 
 /**
@@ -148,6 +165,16 @@ export interface ICacheOptions {
    * Identifier for the key-value store
    */
   storeIdentifier?: string;
+
+  /**
+   * Key-value store backend
+   */
+  storeType?: TCacheStoreType;
+
+  /**
+   * Custom path for custom key-value stores
+   */
+  customPath?: string;
 }
 
 /**