@hellcoder/companion 0.96.0

package/server/update-checker.test.ts

@@ -0,0 +1,306 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// Mock fetch globally
+const mockFetch = vi.fn();
+vi.stubGlobal("fetch", mockFetch);
+
+// Mock settings-manager to control updateChannel
+const mockGetSettings = vi.fn(() => ({
+  updateChannel: "stable" as "stable" | "prerelease",
+}));
+vi.mock("./settings-manager.js", () => ({
+  getSettings: () => mockGetSettings(),
+}));
+
+let checker: typeof import("./update-checker.js");
+
+beforeEach(async () => {
+  vi.resetModules();
+  mockFetch.mockReset();
+  mockGetSettings.mockReturnValue({ updateChannel: "stable" });
+  checker = await import("./update-checker.js");
+});
+
+afterEach(() => {
+  checker.stopPeriodicCheck();
+});
+
+// ===========================================================================
+// isNewerVersion — stable versions
+// ===========================================================================
+describe("isNewerVersion", () => {
+  it("returns true when major version is higher", () => {
+    expect(checker.isNewerVersion("2.0.0", "1.0.0")).toBe(true);
+  });
+
+  it("returns true when minor version is higher", () => {
+    expect(checker.isNewerVersion("1.1.0", "1.0.0")).toBe(true);
+  });
+
+  it("returns true when patch version is higher", () => {
+    expect(checker.isNewerVersion("1.0.1", "1.0.0")).toBe(true);
+  });
+
+  it("returns false when versions are equal", () => {
+    expect(checker.isNewerVersion("1.0.0", "1.0.0")).toBe(false);
+  });
+
+  it("returns false when version is lower", () => {
+    expect(checker.isNewerVersion("1.0.0", "1.0.1")).toBe(false);
+    expect(checker.isNewerVersion("0.9.0", "1.0.0")).toBe(false);
+  });
+});
+
+// ===========================================================================
+// isNewerVersion — prerelease versions
+// ===========================================================================
+describe("isNewerVersion (prerelease)", () => {
+  // Stable release is newer than prerelease of the same core version
+  it("stable is newer than prerelease of same core version", () => {
+    expect(checker.isNewerVersion("1.0.0", "1.0.0-preview.1")).toBe(true);
+  });
+
+  // Prerelease is older than stable of the same core version
+  it("prerelease is older than stable of same core version", () => {
+    expect(checker.isNewerVersion("1.0.0-preview.1", "1.0.0")).toBe(false);
+  });
+
+  // Higher core version prerelease is newer than lower core stable
+  it("higher core prerelease is newer than lower core stable", () => {
+    expect(checker.isNewerVersion("1.1.0-preview.1", "1.0.0")).toBe(true);
+  });
+
+  // Later prerelease of same core is newer
+  it("later prerelease of same core is newer", () => {
+    expect(checker.isNewerVersion("1.0.0-preview.2", "1.0.0-preview.1")).toBe(true);
+  });
+
+  // Earlier prerelease of same core is older
+  it("earlier prerelease of same core is older", () => {
+    expect(checker.isNewerVersion("1.0.0-preview.1", "1.0.0-preview.2")).toBe(false);
+  });
+
+  // Handles timestamp-based prerelease identifiers
+  it("compares timestamp-based prerelease identifiers correctly", () => {
+    expect(checker.isNewerVersion(
+      "0.66.0-preview.20260228140000.abc1234",
+      "0.66.0-preview.20260228120000.def5678",
+    )).toBe(true);
+  });
+
+  // Equal prerelease versions
+  it("returns false for equal prerelease versions", () => {
+    expect(checker.isNewerVersion("1.0.0-preview.1", "1.0.0-preview.1")).toBe(false);
+  });
+
+  // Alphanumeric prerelease identifiers compared lexically
+  it("compares alphanumeric prerelease identifiers lexically", () => {
+    expect(checker.isNewerVersion("1.0.0-beta.1", "1.0.0-alpha.1")).toBe(true);
+    expect(checker.isNewerVersion("1.0.0-alpha.1", "1.0.0-beta.1")).toBe(false);
+  });
+});
+
+// ===========================================================================
+// Prerelease update-channel regression tests (THE-216)
+//
+// The preview workflow publishes versions with a patch-core bump so that
+// prerelease builds are always semver-ahead of the current stable line.
+// These tests lock in the intended behavior to prevent regressions.
+// ===========================================================================
+describe("isNewerVersion — prerelease channel regressions (THE-216)", () => {
+  // A same-core prerelease (the old, broken format) must NOT be considered
+  // newer than the stable release it was derived from.
+  it("same-core prerelease is NOT newer than stable (old broken format)", () => {
+    // e.g. stable 0.68.0, preview publishes 0.68.0-preview.20260301120000.abc1234
+    expect(checker.isNewerVersion("0.68.0-preview.20260301120000.abc1234", "0.68.0")).toBe(false);
+  });
+
+  // A patch-bumped prerelease (the fixed format) IS newer than the stable
+  // release it was derived from.
+  it("patch-bumped prerelease IS newer than stable (fixed format)", () => {
+    // e.g. stable 0.68.0, preview publishes 0.68.1-preview.20260301120000.abc1234
+    expect(checker.isNewerVersion("0.68.1-preview.20260301120000.abc1234", "0.68.0")).toBe(true);
+  });
+
+  // Successive preview builds (same core, increasing timestamps) stay
+  // monotonically ordered.
+  it("later timestamp preview is newer than earlier timestamp preview", () => {
+    expect(checker.isNewerVersion(
+      "0.68.1-preview.20260301140000.abc1234",
+      "0.68.1-preview.20260301120000.def5678",
+    )).toBe(true);
+  });
+
+  // After a new stable release that matches or exceeds the preview core,
+  // the old preview is no longer considered newer.
+  it("stable release at preview core supersedes the preview", () => {
+    // When 0.68.1 stable is released, the preview 0.68.1-preview.* is older
+    expect(checker.isNewerVersion("0.68.1-preview.20260301120000.abc1234", "0.68.1")).toBe(false);
+  });
+
+  // A new stable that leapfrogs past the preview core is newer.
+  it("higher stable is newer than older-core preview", () => {
+    expect(checker.isNewerVersion("0.69.0", "0.68.1-preview.20260301120000.abc1234")).toBe(true);
+  });
+});
+
+// ===========================================================================
+// getCurrentVersion
+// ===========================================================================
+describe("getCurrentVersion", () => {
+  it("returns a semver string", () => {
+    const version = checker.getCurrentVersion();
+    expect(version).toMatch(/^\d+\.\d+\.\d+/);
+  });
+});
+
+// ===========================================================================
+// getUpdateState
+// ===========================================================================
+describe("getUpdateState", () => {
+  it("returns initial state with current version and no latest version", () => {
+    const state = checker.getUpdateState();
+    expect(state.currentVersion).toBe(checker.getCurrentVersion());
+    expect(state.latestVersion).toBeNull();
+    expect(state.isServiceMode).toBe(false);
+    expect(state.checking).toBe(false);
+    expect(state.updateInProgress).toBe(false);
+    expect(state.channel).toBe("stable");
+  });
+});
+
+// ===========================================================================
+// checkForUpdate
+// ===========================================================================
+describe("checkForUpdate", () => {
+  it("fetches from stable dist-tag by default", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ version: "99.0.0" }),
+    });
+
+    await checker.checkForUpdate();
+
+    // Should use /latest for stable channel. The "/" in "@hellcoder/companion"
+    // is URL-encoded to "%2F" because that is what npm's registry requires.
+    expect(mockFetch).toHaveBeenCalledWith(
+      "https://registry.npmjs.org/%40hellcoder%2Fcompanion/latest",
+      expect.objectContaining({
+        headers: { Accept: "application/json" },
+      }),
+    );
+    const state = checker.getUpdateState();
+    expect(state.latestVersion).toBe("99.0.0");
+    expect(state.lastChecked).toBeGreaterThan(0);
+    expect(state.channel).toBe("stable");
+  });
+
+  it("fetches from next dist-tag when channel is prerelease", async () => {
+    mockGetSettings.mockReturnValue({ updateChannel: "prerelease" });
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ version: "99.0.0-preview.1" }),
+    });
+
+    await checker.checkForUpdate();
+
+    // Should use /next for prerelease channel. Scoped name is URL-encoded.
+    expect(mockFetch).toHaveBeenCalledWith(
+      "https://registry.npmjs.org/%40hellcoder%2Fcompanion/next",
+      expect.objectContaining({
+        headers: { Accept: "application/json" },
+      }),
+    );
+    const state = checker.getUpdateState();
+    expect(state.latestVersion).toBe("99.0.0-preview.1");
+    expect(state.channel).toBe("prerelease");
+  });
+
+  // When switching channels, the previous channel's latestVersion must be
+  // cleared to avoid cross-channel stale comparisons.
+  it("clears latestVersion when channel changes to avoid stale comparison", async () => {
+    // First check on stable channel sets a latestVersion
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ version: "99.0.0" }),
+    });
+    await checker.checkForUpdate();
+    expect(checker.getUpdateState().latestVersion).toBe("99.0.0");
+
+    // Switch to prerelease but fetch fails
+    mockGetSettings.mockReturnValue({ updateChannel: "prerelease" });
+    mockFetch.mockRejectedValueOnce(new Error("Network error"));
+    await checker.checkForUpdate();
+
+    // latestVersion should be null (not the stale stable version)
+    const state = checker.getUpdateState();
+    expect(state.latestVersion).toBeNull();
+    expect(state.channel).toBe("prerelease");
+  });
+
+  it("handles fetch errors gracefully", async () => {
+    mockFetch.mockRejectedValueOnce(new Error("Network error"));
+
+    await checker.checkForUpdate();
+
+    const state = checker.getUpdateState();
+    expect(state.latestVersion).toBeNull();
+  });
+
+  it("handles non-ok response gracefully", async () => {
+    mockFetch.mockResolvedValueOnce({ ok: false, status: 500 });
+
+    await checker.checkForUpdate();
+
+    const state = checker.getUpdateState();
+    expect(state.latestVersion).toBeNull();
+  });
+});
+
+// ===========================================================================
+// isUpdateAvailable
+// ===========================================================================
+describe("isUpdateAvailable", () => {
+  it("returns false when no latest version is set", () => {
+    expect(checker.isUpdateAvailable()).toBe(false);
+  });
+
+  it("returns true when latest is newer than current", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ version: "99.0.0" }),
+    });
+
+    await checker.checkForUpdate();
+    expect(checker.isUpdateAvailable()).toBe(true);
+  });
+
+  it("returns false when latest equals current", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ version: checker.getCurrentVersion() }),
+    });
+
+    await checker.checkForUpdate();
+    expect(checker.isUpdateAvailable()).toBe(false);
+  });
+});
+
+// ===========================================================================
+// setServiceMode / setUpdateInProgress
+// ===========================================================================
+describe("state setters", () => {
+  it("setServiceMode updates isServiceMode", () => {
+    checker.setServiceMode(true);
+    expect(checker.getUpdateState().isServiceMode).toBe(true);
+    checker.setServiceMode(false);
+    expect(checker.getUpdateState().isServiceMode).toBe(false);
+  });
+
+  it("setUpdateInProgress updates updateInProgress", () => {
+    checker.setUpdateInProgress(true);
+    expect(checker.getUpdateState().updateInProgress).toBe(true);
+    checker.setUpdateInProgress(false);
+    expect(checker.getUpdateState().updateInProgress).toBe(false);
+  });
+});

package/server/update-checker.ts

@@ -0,0 +1,197 @@
+import { readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getSettings, type UpdateChannel } from "./settings-manager.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Read current version from package.json
+const packageJsonPath = resolve(__dirname, "..", "package.json");
+const currentVersion: string = JSON.parse(
+  readFileSync(packageJsonPath, "utf-8"),
+).version;
+
+// Package name is URL-encoded because scoped npm packages (e.g. @hellcoder/companion)
+// require the slash to be escaped in registry URLs.
+const NPM_PACKAGE_NAME = "@hellcoder/companion";
+const NPM_REGISTRY_BASE = `https://registry.npmjs.org/${encodeURIComponent(NPM_PACKAGE_NAME)}`;
+const CHECK_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
+const INITIAL_DELAY_MS = 10_000; // 10 seconds after boot
+
+interface UpdateState {
+  currentVersion: string;
+  latestVersion: string | null;
+  lastChecked: number;
+  isServiceMode: boolean;
+  checking: boolean;
+  updateInProgress: boolean;
+  channel: UpdateChannel;
+}
+
+const state: UpdateState = {
+  currentVersion,
+  latestVersion: null,
+  lastChecked: 0,
+  isServiceMode: false,
+  checking: false,
+  updateInProgress: false,
+  channel: "stable",
+};
+
+export function getUpdateState(): Readonly<UpdateState> {
+  return { ...state };
+}
+
+export function getCurrentVersion(): string {
+  return currentVersion;
+}
+
+/** Returns the npm registry URL for the given dist-tag. */
+function getRegistryUrl(channel: UpdateChannel): string {
+  const distTag = channel === "prerelease" ? "next" : "latest";
+  return `${NPM_REGISTRY_BASE}/${distTag}`;
+}
+
+export async function checkForUpdate(): Promise<void> {
+  if (state.checking) return;
+  state.checking = true;
+  try {
+    // Read channel from settings on each check so switching is immediate
+    const channel = getSettings().updateChannel;
+    if (channel !== state.channel) {
+      state.latestVersion = null; // avoid cross-channel stale comparison
+    }
+    state.channel = channel;
+    const url = getRegistryUrl(channel);
+
+    const res = await fetch(url, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (res.ok) {
+      const data = (await res.json()) as { version: string };
+      state.latestVersion = data.version;
+      state.lastChecked = Date.now();
+      if (isUpdateAvailable()) {
+        console.log(
+          `[update-checker] Update available (${channel}): ${currentVersion} -> ${state.latestVersion}`,
+        );
+      }
+    }
+  } catch (err) {
+    console.warn(
+      "[update-checker] Failed to check for updates:",
+      err instanceof Error ? err.message : String(err),
+    );
+  } finally {
+    state.checking = false;
+  }
+}
+
+export function setServiceMode(isService: boolean): void {
+  state.isServiceMode = isService;
+}
+
+export function setUpdateInProgress(inProgress: boolean): void {
+  state.updateInProgress = inProgress;
+}
+
+export function isUpdateAvailable(): boolean {
+  if (!state.latestVersion) return false;
+  return isNewerVersion(state.latestVersion, currentVersion);
+}
+
+/**
+ * Parse a semver string into its components.
+ * Handles versions like "1.2.3", "1.2.3-preview.20260228120000.abc1234"
+ */
+function parseSemver(v: string): { major: number; minor: number; patch: number; prerelease: string[] } {
+  const [corePart, ...prereleaseParts] = v.split("-");
+  const prerelease = prereleaseParts.length > 0 ? prereleaseParts.join("-").split(".") : [];
+  const parts = corePart.split(".").map(Number);
+  return {
+    major: parts[0] || 0,
+    minor: parts[1] || 0,
+    patch: parts[2] || 0,
+    prerelease,
+  };
+}
+
+/**
+ * Compare two semver prerelease identifier arrays.
+ * Returns -1 if a < b, 0 if a == b, 1 if a > b.
+ * A version with no prerelease identifiers has higher precedence than one with.
+ */
+function comparePrereleaseArrays(a: string[], b: string[]): number {
+  // No prerelease on both = equal
+  if (a.length === 0 && b.length === 0) return 0;
+  // No prerelease > has prerelease (stable is newer than prerelease of same core version)
+  if (a.length === 0) return 1;
+  if (b.length === 0) return -1;
+
+  const maxLen = Math.max(a.length, b.length);
+  for (let i = 0; i < maxLen; i++) {
+    // Fewer fields = lower precedence
+    if (i >= a.length) return -1;
+    if (i >= b.length) return 1;
+
+    const aNum = Number(a[i]);
+    const bNum = Number(b[i]);
+    const aIsNum = !isNaN(aNum);
+    const bIsNum = !isNaN(bNum);
+
+    if (aIsNum && bIsNum) {
+      if (aNum > bNum) return 1;
+      if (aNum < bNum) return -1;
+    } else if (aIsNum) {
+      // Numeric identifiers have lower precedence than alphanumeric
+      return -1;
+    } else if (bIsNum) {
+      return 1;
+    } else {
+      // Both alphanumeric: compare lexically
+      if (a[i] > b[i]) return 1;
+      if (a[i] < b[i]) return -1;
+    }
+  }
+  return 0;
+}
+
+/**
+ * Prerelease-aware semver comparison: returns true if a > b.
+ * Handles both stable versions (1.2.3) and prerelease versions
+ * (1.2.3-preview.20260228120000.abc1234).
+ */
+export function isNewerVersion(a: string, b: string): boolean {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+
+  // Compare major.minor.patch
+  if (pa.major !== pb.major) return pa.major > pb.major;
+  if (pa.minor !== pb.minor) return pa.minor > pb.minor;
+  if (pa.patch !== pb.patch) return pa.patch > pb.patch;
+
+  // Core versions are equal — compare prerelease
+  return comparePrereleaseArrays(pa.prerelease, pb.prerelease) > 0;
+}
+
+let intervalId: ReturnType<typeof setInterval> | null = null;
+
+export function startPeriodicCheck(): void {
+  // Initial check after a short delay
+  setTimeout(() => {
+    checkForUpdate();
+  }, INITIAL_DELAY_MS);
+
+  // Periodic checks
+  intervalId = setInterval(() => {
+    checkForUpdate();
+  }, CHECK_INTERVAL_MS);
+}
+
+export function stopPeriodicCheck(): void {
+  if (intervalId) {
+    clearInterval(intervalId);
+    intervalId = null;
+  }
+}