feat(cli): add update checks

.github/workflows/go.yml

@@ -29,7 +29,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        go-version: ['1.23.x', '1.24.x']
+        go-version: ['1.24.x']
     steps:
       - name: Checkout Repo
         uses: actions/checkout@main

genkit-tools/cli/package.json

@@ -22,7 +22,7 @@
     "build:watch": "tsc --watch",
     "compile:bun": "bun build src/bin/genkit.ts --compile --outfile dist/bin/genkit --minify",
     "test": "jest --verbose",
-    "genversion": "genversion -esf src/utils/version.ts"
+    "genversion": "genversion -esf --property name,version src/utils/version.ts"
   },
   "repository": {
     "type": "git",
@@ -40,13 +40,14 @@
     "get-port": "5.1.1",
     "@inquirer/prompts": "^7.8.0",
     "open": "^6.3.0",
-    "ora": "^5.4.1"
+    "ora": "^5.4.1",
+    "semver": "^7.7.2"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
-    "@types/inquirer": "^8.1.3",
     "@types/jest": "^29.5.12",
     "@types/node": "^20.11.19",
+    "@types/semver": "^7.7.0",
     "bun-types": "^1.2.16",
     "genversion": "^3.2.0",
     "jest": "^29.7.0",

genkit-tools/cli/src/cli.ts

@@ -38,6 +38,7 @@ import {
 import { start } from './commands/start';
 import { uiStart } from './commands/ui-start';
 import { uiStop } from './commands/ui-stop';
+import { showUpdateNotification } from './utils/updates';
 import { version } from './utils/version';
 
 /**
@@ -66,6 +67,7 @@ export async function startCLI(): Promise<void> {
     .name('genkit')
     .description('Genkit CLI')
     .version(version)
+    .option('--no-update-notification', 'Do not show update notification')
     .hook('preAction', async (_, actionCommand) => {
       await notifyAnalyticsIfFirstRun();
 
@@ -87,6 +89,21 @@ export async function startCLI(): Promise<void> {
       await record(new RunCommandEvent(commandName));
     });
 
+  // Check for updates and show notification if available,
+  // unless --no-update-notification is set
+  // Run this synchronously to ensure it shows before command execution
+  const hasNoUpdateNotification = process.argv.includes(
+    '--no-update-notification'
+  );
+  if (!hasNoUpdateNotification) {
+    try {
+      await showUpdateNotification();
+    } catch (e) {
+      logger.debug('Failed to show update notification', e);
+      // Silently ignore errors - update notifications shouldn't break the CLI
+    }
+  }
+
   // When running as a spawned UI server process, argv[1] will be '__server-harness'
   // instead of a normal command. This allows the same binary to serve both CLI and server roles.
   if (process.argv[2] === SERVER_HARNESS_COMMAND) {

genkit-tools/cli/src/commands/config.ts

@@ -25,6 +25,9 @@ import {
 import * as clc from 'colorette';
 import { Command } from 'commander';
 
+export const UPDATE_NOTIFICATIONS_OPT_OUT_CONFIG_TAG =
+  'updateNotificationsOptOut';
+
 const CONFIG_TAGS: Record<
   string,
   (value: string) => string | boolean | number
@@ -38,6 +41,15 @@ const CONFIG_TAGS: Record<
       return o;
     }
   },
+  [UPDATE_NOTIFICATIONS_OPT_OUT_CONFIG_TAG]: (value) => {
+    let o: boolean | undefined;
+    try {
+      o = JSON.parse(value);
+    } finally {
+      if (typeof o !== 'boolean') throw new Error('Expected boolean');
+      return o;
+    }
+  },
 };
 
 export const config = new Command('config');

genkit-tools/cli/src/utils/updates.ts

@@ -0,0 +1,249 @@
+/**
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { GenkitToolsError } from '@genkit-ai/tools-common/manager';
+import { getUserSettings, logger } from '@genkit-ai/tools-common/utils';
+import axios, { AxiosInstance } from 'axios';
+import * as clc from 'colorette';
+import { arch, platform } from 'os';
+import semver from 'semver';
+import { UPDATE_NOTIFICATIONS_OPT_OUT_CONFIG_TAG } from '../commands/config';
+import { detectCLIRuntime } from '../utils/runtime-detector';
+import {
+  version as currentVersion,
+  name as packageName,
+} from '../utils/version';
+
+const GCS_BUCKET_URL = 'https://storage.googleapis.com/genkit-assets-cli';
+const CLI_DOCS_URL = 'https://genkit.dev/docs/devtools/';
+const AXIOS_INSTANCE: AxiosInstance = axios.create({
+  timeout: 3000,
+});
+
+/**
+ * Interface for update check result
+ */
+export interface UpdateCheckResult {
+  hasUpdate: boolean;
+  currentVersion: string;
+  latestVersion: string;
+}
+
+/**
+ * Returns the current CLI version, normalized.
+ */
+export function getCurrentVersion(): string {
+  return normalizeVersion(currentVersion);
+}
+
+/**
+ * Normalizes a version string by removing a leading 'v' if present.
+ * @param version - The version string to normalize
+ * @returns The normalized version string
+ */
+function normalizeVersion(version: string): string {
+  return version.replace(/^v/, '');
+}
+
+/**
+ * Interface for the Google Cloud Storage latest.json response
+ */
+interface GCSLatestResponse {
+  channel: string;
+  latestVersion: string;
+  lastUpdated: string;
+  platforms: Record<
+    string,
+    {
+      url: string;
+      version: string;
+      versionedUrl: string;
+    }
+  >;
+}
+
+/**
+ * Interface for npm registry response
+ */
+interface NpmRegistryResponse {
+  'dist-tags': {
+    latest: string;
+    [key: string]: string;
+  };
+  versions: Record<string, unknown>;
+}
+
+/**
+ * Fetches the latest release data from GCS.
+ */
+async function getGCSLatestData(): Promise<GCSLatestResponse> {
+  const response = await AXIOS_INSTANCE.get(`${GCS_BUCKET_URL}/latest.json`);
+
+  if (response.status !== 200) {
+    throw new GenkitToolsError(
+      `Failed to fetch GCS latest.json: ${response.statusText}`
+    );
+  }
+
+  return response.data as GCSLatestResponse;
+}
+
+/**
+ * Gets the latest CLI version from npm registry for non-binary installations.
+ * @param ignoreRC - If true, ignore prerelease versions (default: true)
+ */
+export async function getLatestVersionFromNpm(
+  ignoreRC: boolean = true
+): Promise<string | null> {
+  try {
+    const response = await AXIOS_INSTANCE.get(
+      `https://registry.npmjs.org/${packageName}`
+    );
+
+    if (response.status !== 200) {
+      throw new GenkitToolsError(
+        `Failed to fetch npm versions: ${response.statusText}`
+      );
+    }
+
+    const data: NpmRegistryResponse = response.data;
+
+    // Prefer dist-tags.latest if valid and not a prerelease (if ignoreRC)
+    const latest = data['dist-tags']?.latest;
+    if (latest) {
+      const clean = normalizeVersion(latest);
+      if (semver.valid(clean) && (!ignoreRC || !semver.prerelease(clean))) {
+        return clean;
+      }
+    }
+
+    // Fallback: find the highest valid version in versions
+    const versions = Object.keys(data.versions)
+      .map(normalizeVersion)
+      .filter((v) => semver.valid(v) && (!ignoreRC || !semver.prerelease(v)));
+
+    if (versions.length === 0) {
+      return null;
+    }
+
+    // Sort by semver descending (newest first)
+    versions.sort(semver.rcompare);
+    return versions[0];
+  } catch (error: unknown) {
+    if (error instanceof GenkitToolsError) {
+      throw error;
+    }
+
+    throw new GenkitToolsError(
+      `Failed to fetch npm versions: ${(error as Error)?.message ?? String(error)}`
+    );
+  }
+}
+
+/**
+ * Checks if update notifications are disabled via environment variable or user config.
+ */
+function isUpdateNotificationsDisabled(): boolean {
+  if (process.env.GENKIT_CLI_DISABLE_UPDATE_NOTIFICATIONS === 'true') {
+    return true;
+  }
+  const userSettings = getUserSettings();
+  return Boolean(userSettings[UPDATE_NOTIFICATIONS_OPT_OUT_CONFIG_TAG]);
+}
+
+/**
+ * Gets the latest version and update message for compiled binary installations.
+ */
+async function getBinaryUpdateInfo(): Promise<string | null> {
+  const gcsLatestData = await getGCSLatestData();
+  const machine = `${platform}-${arch}`;
+  const platformData = gcsLatestData.platforms[machine];
+
+  if (!platformData) {
+    logger.debug(`No update information for platform: ${machine}`);
+    return null;
+  }
+
+  const latestVersion = normalizeVersion(gcsLatestData.latestVersion);
+  return latestVersion;
+}
+
+/**
+ * Gets the latest version and update message for npm installations.
+ */
+async function getNpmUpdateInfo(): Promise<string | null> {
+  const latestVersion = await getLatestVersionFromNpm();
+  if (!latestVersion) {
+    logger.debug('No available versions found from npm.');
+    return null;
+  }
+  return latestVersion;
+}
+
+/**
+ * Shows an update notification if a new version is available.
+ * This function is designed to be called from the CLI entry point.
+ * It can be disabled by the user's configuration or environment variable.
+ */
+export async function showUpdateNotification(): Promise<void> {
+  try {
+    if (isUpdateNotificationsDisabled()) {
+      return;
+    }
+
+    const { isCompiledBinary } = detectCLIRuntime();
+    const updateInfo = isCompiledBinary
+      ? await getBinaryUpdateInfo()
+      : await getNpmUpdateInfo();
+
+    if (!updateInfo) {
+      return;
+    }
+
+    const latestVersion = updateInfo;
+    const current = normalizeVersion(currentVersion);
+
+    if (!semver.valid(latestVersion) || !semver.valid(current)) {
+      logger.debug(
+        `Invalid semver: current=${current}, latest=${latestVersion}`
+      );
+      return;
+    }
+
+    if (!semver.gt(latestVersion, current)) {
+      return;
+    }
+
+    // Determine install method and update command for message
+    const installMethod = isCompiledBinary
+      ? 'installer script'
+      : 'your package manager';
+    const updateCommand = isCompiledBinary
+      ? 'curl -sL cli.genkit.dev | uninstall=true bash'
+      : 'npm install -g genkit-cli';
+
+    const updateNotificationMessage =
+      `Update available ${clc.gray(`v${current}`)} → ${clc.green(`v${latestVersion}`)}\n` +
+      `To update to the latest version using ${installMethod}, run\n${clc.cyan(updateCommand)}\n` +
+      `For other CLI management options, visit ${CLI_DOCS_URL}\n` +
+      `${clc.dim('Run')} ${clc.bold('genkit config set updateNotificationsOptOut true')} ${clc.dim('to disable these notifications')}\n`;
+
+    logger.info(`\n${updateNotificationMessage}`);
+  } catch (e) {
+    // Silently fail - update notifications shouldn't break the CLI
+    logger.debug('Failed to show update notification', e);
+  }
+}