@skrr-ai/cli 0.1.94 → 0.1.96

package/dist/lib/update-check.d.ts

@@ -1,44 +1,66 @@
-export type CliInstallKind = 'npm-global' | 'npm-local' | 'dev' | 'bundled' | 'other';
-interface CheckCache {
-    /** Epoch ms of the last successful refresh. */
+export type CliInstallKind = 'npm-global' | 'npm-local' | 'dev' | 'bundled' | 'image' | 'homebrew' | 'other';
+export interface CliUpdateAttempt {
+    status: 'queued' | 'running' | 'succeeded' | 'failed';
+    version: string;
+    attemptedAt: number;
+    updatedAt?: number;
+    startedAt?: number;
+    finishedAt?: number;
+    installedVersion?: string;
+    message?: string;
+    packageRoot?: string;
+    npmPath?: string;
+    coordinationVersion?: number;
+    workerPid?: number;
+    interrupted?: boolean;
+}
+export interface CheckCache {
     lastCheckAt: number;
-    /** Latest advertised CLI version, or null if the API had none. */
     latest: string | null;
-    /** npm package to update (advisory copy), or null. */
     npmPackage: string | null;
-    /** baseURL the cache was fetched against — invalidates on server switch. */
     baseURL: string;
-    /** Resolved install shape, classified during the last refresh. */
     install?: {
         kind: CliInstallKind;
         writable?: boolean;
     };
-    /** Recorded BEFORE a background self-update is scheduled. */
+    packageRoot?: string;
+    npmGlobalRoot?: string | null;
     autoUpdate?: {
         attemptedAt: number;
         version: string;
+        status?: CliUpdateAttempt['status'];
+        message?: string;
     };
 }
-/** Trailing-slash- and case-insensitive normalization for baseURL compares. */
+export interface CliUpdateOptions {
+    currentVersion: string;
+    baseURL: string;
+    force?: boolean;
+    env?: NodeJS.ProcessEnv;
+    argv?: readonly string[];
+}
+export interface CliUpdateStatus {
+    component: 'cli';
+    runningVersion: string;
+    installedVersion: string | null;
+    offeredVersion: string | null;
+    owner: CliInstallKind;
+    state: 'up-to-date' | 'update-available' | 'pending' | 'restart-pending' | 'failed' | 'managed' | 'unknown' | 'check-failed';
+    autoUpdateAllowed: boolean;
+    autoUpdateReason: string | null;
+    command: string;
+    lastCheckAt: number | null;
+    lastAttempt: CliUpdateAttempt | null;
+    logPath: string;
+    message?: string;
+}
 export declare function normalizeBaseUrl(url: string): string;
-/**
- * True when the advisory must stay silent regardless of version state:
- * explicit suppression, a desktop-app-bundled CLI (which auto-updates with
- * the app and must not be told to `npm update -g`), or an image-baked install
- * the control plane owns.
- */
 export declare function isNudgeSuppressed(env?: NodeJS.ProcessEnv): boolean;
-/** True when the background self-update is allowed to run at all. Suppression
- *  implies no auto-update — a user who asked for silence did not ask for a
- *  silent mutation of their global npm. */
 export declare function isAutoUpdateSuppressed(env?: NodeJS.ProcessEnv): boolean;
-/**
- * True iff `current` is strictly older than `latest` by numeric release
- * core. Conservative: any unparseable input returns false (no nudge).
- * Prerelease suffixes are ignored, so `0.2.0-rc.1` is treated as `0.2.0` —
- * we never nag someone testing a prerelease of the latest line.
- */
 export declare function isOlderVersion(current: string, latest: string): boolean;
+/** Per-user leases cannot coordinate a global prefix shared with another OS
+ * user. Only private user-owned prefixes participate in managed replacement. */
+export declare function isPrivateCliPrefix(root: string): boolean;
 /**
  * Resolve the package directory this process was launched from when it lives
  * under `node_modules/@skrr-ai/cli` (any npm install — global or project-local),
@@ -54,17 +76,12 @@ export declare function resolveCliPackageDir(argv?: readonly string[]): string |
  * dir beside `dist` exists only in a checkout — published packages ship
  * `dist` and no `src`.
  */
-export declare function classifyCliInstall(env: NodeJS.ProcessEnv, argv: readonly string[], npmGlobalRoot: string | null): {
+export declare function classifyCliInstall(env: NodeJS.ProcessEnv, argv: readonly string[], npmGlobalRoot: string | null, probeWritable?: boolean): {
     kind: CliInstallKind;
     writable?: boolean;
 };
-/**
- * Build the one-line stderr advisory, or null when no nudge is warranted.
- * `installKind` tailors the command to the bytes' owner: a project-local dep
- * is updated inside its project, a dev checkout is rebuilt — telling either
- * to `npm update -g` would fix the wrong install.
- */
-export declare function buildNudgeLine(currentVersion: string, latest: string | null, npmPackage: string | null, installKind?: CliInstallKind): string | null;
+export declare function cliUpdateCommand(owner: CliInstallKind): string;
+export declare function buildNudgeLine(currentVersion: string, latest: string | null, _npmPackage: string | null, installKind?: CliInstallKind): string | null;
 export type CliUpdateAction = {
     type: 'nudge';
     line: string;
@@ -74,15 +91,6 @@ export type CliUpdateAction = {
     pkg: string;
     line: string;
 } | null;
-/**
- * Decide, synchronously and from cache alone, what this command should do
- * about its version state. Pure — exported for direct unit testing.
- *
- * AUTO-UPDATE fires at most once per TTL window per target version, and only
- * for a provably writable npm-global install on an interactive TTY. An attempt
- * that didn't take (still outdated next run) falls back to the manual nudge
- * rather than retrying immediately.
- */
 export declare function decideCliUpdateAction(args: {
     currentVersion: string;
     cache: CheckCache | null;
@@ -90,15 +98,15 @@ export declare function decideCliUpdateAction(args: {
     isTTY: boolean;
     now?: number;
 }): CliUpdateAction;
-/**
- * Entry point, called once per command from `BaseCommand.init()`.
- *
- * Synchronous by design: it decides from the cache (no network on the hot
- * path) and only kicks off a background refresh when the cache is stale,
- * missing, or from a different server. Returns immediately.
- */
-export declare function maybeWarnOutdatedCli(opts: {
-    currentVersion: string;
-    baseURL: string;
-}): void;
-export {};
+/** Cached, read-only status: no network, child process, lease, or mutation. */
+export declare function readCliUpdateStatus(opts: CliUpdateOptions): CliUpdateStatus;
+/** Bounded discovery, also usable without a daemon, account, or TTY. */
+export declare function checkCliUpdate(opts: CliUpdateOptions): Promise<CliUpdateStatus>;
+/** Queue an exact version through the owning global npm prefix. The current
+ * invocation stays leased, so replacement starts after it and peers exit. */
+export declare function performCliUpdate(opts: CliUpdateOptions): Promise<CliUpdateStatus>;
+/** One startup advisory across oclif command families. Awaiting bounded
+ * discovery makes the first invocation useful rather than losing its fetch
+ * when a short command exits. No update/check errors can break a command. */
+export declare function maybeWarnOutdatedCli(opts: CliUpdateOptions): Promise<void>;
+export declare function shouldCheckCliUpdateAtStartup(argv: readonly string[], isTTY: boolean, env?: NodeJS.ProcessEnv): boolean;