add daily update check with release notice (#33)

* feat(cli): add daily update check with release notice

Query GitHub Releases at most once every 24h and show a one-line
notice on stderr when a newer version is available. Skipped for dev
builds, CI environments, and when N8N_CLI_DISABLE_UPDATE_CHECK=1.
Cache is stored under XDG_CACHE_HOME / Library/Caches / LOCALAPPDATA
depending on platform.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* chore: bump version to 2.1.1

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: syucream

package.json

@@ -1,6 +1,6 @@
 {
   "name": "n8n-cli",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "module": "src/index.ts",
   "type": "module",
   "private": true,

src/cli/update-check.ts

@@ -0,0 +1,169 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+declare const CLI_VERSION: string;
+
+const REPO = "ubie-oss/n8n-cli";
+const LATEST_RELEASE_URL = `https://api.github.com/repos/${REPO}/releases/latest`;
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 3000;
+
+interface CacheEntry {
+  lastCheckedAt: string;
+  latestVersion: string | null;
+}
+
+/** Resolve the cache file path in a platform-appropriate location. */
+export function cacheFilePath(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+  home: string = os.homedir(),
+): string {
+  if (env.XDG_CACHE_HOME) {
+    return path.join(env.XDG_CACHE_HOME, "n8n-cli", "update-check.json");
+  }
+  switch (platform) {
+    case "darwin":
+      return path.join(home, "Library", "Caches", "n8n-cli", "update-check.json");
+    case "win32":
+      return path.join(
+        env.LOCALAPPDATA ?? path.join(home, "AppData", "Local"),
+        "n8n-cli",
+        "Cache",
+        "update-check.json",
+      );
+    default:
+      return path.join(home, ".cache", "n8n-cli", "update-check.json");
+  }
+}
+
+/**
+ * Compare two semver-ish versions. Returns 1 if a>b, -1 if a<b, 0 if equal.
+ * Strips leading "v" and trailing "-dirty"/pre-release suffixes for comparison.
+ */
+export function compareVersions(a: string, b: string): number {
+  const normalize = (v: string): number[] =>
+    v
+      .replace(/^v/, "")
+      .split("-")[0]!
+      .split(".")
+      .map((s) => Number.parseInt(s, 10))
+      .map((n) => (Number.isNaN(n) ? 0 : n));
+
+  const parsedA = normalize(a);
+  const parsedB = normalize(b);
+  const len = Math.max(parsedA.length, parsedB.length);
+  for (let i = 0; i < len; i++) {
+    const x = parsedA[i] ?? 0;
+    const y = parsedB[i] ?? 0;
+    if (x > y) return 1;
+    if (x < y) return -1;
+  }
+  return 0;
+}
+
+function isCheckDisabled(): boolean {
+  if (process.env.N8N_CLI_DISABLE_UPDATE_CHECK === "1") return true;
+  if (process.env.CI === "true" || process.env.CI === "1") return true;
+  return false;
+}
+
+function readCache(filePath: string): CacheEntry | null {
+  try {
+    const raw = fs.readFileSync(filePath, "utf8");
+    const parsed = JSON.parse(raw) as unknown;
+    if (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      typeof (parsed as CacheEntry).lastCheckedAt === "string"
+    ) {
+      return parsed as CacheEntry;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(filePath: string, entry: CacheEntry): void {
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(entry, null, 2));
+  } catch {
+    // ignore — cache write failures must not affect the CLI
+  }
+}
+
+async function fetchLatestVersion(): Promise<string | null> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(LATEST_RELEASE_URL, {
+      headers: {
+        Accept: "application/vnd.github+json",
+        "User-Agent": "n8n-cli-update-check",
+      },
+      signal: controller.signal,
+    });
+    if (!res.ok) return null;
+    const json = (await res.json()) as { tag_name?: unknown };
+    return typeof json.tag_name === "string" ? json.tag_name : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function currentVersion(): string | null {
+  const v = typeof CLI_VERSION !== "undefined" ? CLI_VERSION : "dev";
+  if (v === "dev" || v === "unknown" || v === "") return null;
+  return v;
+}
+
+/**
+ * Kick off an update check. Returns a promise so the caller can await it
+ * before showing the notice. Safe to fire-and-forget if the caller prefers.
+ * Silent on all errors.
+ */
+export async function runUpdateCheck(): Promise<void> {
+  if (isCheckDisabled()) return;
+  if (currentVersion() === null) return;
+
+  const file = cacheFilePath();
+  const cache = readCache(file);
+  const now = Date.now();
+  if (cache) {
+    const last = Date.parse(cache.lastCheckedAt);
+    if (!Number.isNaN(last) && now - last < CHECK_INTERVAL_MS) return;
+  }
+
+  const latest = await fetchLatestVersion();
+  writeCache(file, {
+    lastCheckedAt: new Date(now).toISOString(),
+    latestVersion: latest,
+  });
+}
+
+/**
+ * If a newer version is known (from a prior check), print a one-line notice
+ * to stderr. Never throws.
+ */
+export function maybeShowUpdateNotice(): void {
+  if (isCheckDisabled()) return;
+  const current = currentVersion();
+  if (current === null) return;
+
+  const cache = readCache(cacheFilePath());
+  if (!cache || !cache.latestVersion) return;
+
+  if (compareVersions(cache.latestVersion, current) > 0) {
+    const latest = cache.latestVersion;
+    process.stderr.write(
+      `\n[n8n-cli] A new version ${latest} is available (current: ${current}).\n` +
+        `  Update: git pull && make build  (https://github.com/${REPO}/releases/latest)\n` +
+        `  Silence: export N8N_CLI_DISABLE_UPDATE_CHECK=1\n`,
+    );
+  }
+}

src/index.ts

@@ -12,9 +12,14 @@ import { registerTestCommand } from "./cli/commands/test.ts";
 import { registerTraceCommand } from "./cli/commands/trace.ts";
 import { registerWorkflowCommand } from "./cli/commands/workflow.ts";
 import { createProgram } from "./cli/root.ts";
+import { maybeShowUpdateNotice, runUpdateCheck } from "./cli/update-check.ts";
 
 const program = createProgram();
 
+// Kick off the update check in the background — result is persisted to the
+// cache file and shown on the *next* run (keeps this run's exit path fast).
+const updateCheckPromise = runUpdateCheck().catch(() => {});
+
 // Register commands
 registerWorkflowCommand(program);
 registerExecutionCommand(program);
@@ -32,6 +37,8 @@ registerTraceCommand(program);
 
 try {
   await program.parseAsync(process.argv);
+  await updateCheckPromise;
+  maybeShowUpdateNotice();
 } catch (err) {
   if (err instanceof Error) {
     console.error(`Error: ${err.message}`);

tests/cli/update-check.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import { cacheFilePath, compareVersions } from "@/cli/update-check.ts";
+
+describe("compareVersions", () => {
+  test("returns 0 for equal versions", () => {
+    expect(compareVersions("2.1.0", "2.1.0")).toBe(0);
+  });
+
+  test("returns 1 when a is newer", () => {
+    expect(compareVersions("2.2.0", "2.1.0")).toBe(1);
+    expect(compareVersions("2.1.1", "2.1.0")).toBe(1);
+    expect(compareVersions("3.0.0", "2.9.9")).toBe(1);
+  });
+
+  test("returns -1 when a is older", () => {
+    expect(compareVersions("2.0.9", "2.1.0")).toBe(-1);
+  });
+
+  test("strips leading v prefix", () => {
+    expect(compareVersions("v2.2.0", "2.1.0")).toBe(1);
+    expect(compareVersions("v2.1.0", "v2.1.0")).toBe(0);
+  });
+
+  test("ignores -dirty / pre-release suffixes", () => {
+    expect(compareVersions("2.1.0-dirty", "2.1.0")).toBe(0);
+    expect(compareVersions("2.1.0-rc.1", "2.1.0")).toBe(0);
+  });
+
+  test("handles missing segments as zero", () => {
+    expect(compareVersions("2.1", "2.1.0")).toBe(0);
+    expect(compareVersions("2", "2.0.1")).toBe(-1);
+  });
+});
+
+describe("cacheFilePath", () => {
+  test("honors XDG_CACHE_HOME when set", () => {
+    const p = cacheFilePath({ XDG_CACHE_HOME: "/tmp/xdg" }, "linux", "/home/u");
+    expect(p).toBe("/tmp/xdg/n8n-cli/update-check.json");
+  });
+
+  test("uses ~/Library/Caches on darwin", () => {
+    const p = cacheFilePath({}, "darwin", "/Users/u");
+    expect(p).toBe("/Users/u/Library/Caches/n8n-cli/update-check.json");
+  });
+
+  test("uses LOCALAPPDATA on win32", () => {
+    const p = cacheFilePath(
+      { LOCALAPPDATA: "C:\\Users\\u\\AppData\\Local" },
+      "win32",
+      "C:\\Users\\u",
+    );
+    expect(p).toContain("AppData");
+    expect(p).toContain("n8n-cli");
+    expect(p).toContain("update-check.json");
+  });
+
+  test("falls back to ~/.cache on linux", () => {
+    const p = cacheFilePath({}, "linux", "/home/u");
+    expect(p).toBe("/home/u/.cache/n8n-cli/update-check.json");
+  });
+});