@trolleroof/tui 0.2.3

package/scripts/plugin-update.test.ts

@@ -0,0 +1,318 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import {
+  fetchRemoteReleaseManifest,
+  formatUpdateStatusLine,
+  formatUpdateVersions,
+  isDirectoryMarketplace,
+  nudgeHookOutput,
+  parsePluginUpdateAction,
+  readInstalledPlugin,
+  readUpdateFlag,
+  resolvePluginUpdatePaths,
+  runPluginUpdateCheck,
+  runPluginUpdateClear,
+  runPluginUpdateNudge,
+  shouldSkipUpdateCheck,
+  writeStatusLineShim,
+} from "./plugin-update.js";
+
+function tempPaths(homeDir = mkdtempSync(join(tmpdir(), "gamepigeon-update-"))) {
+  const claudeConfigDir = join(homeDir, ".claude");
+  mkdirSync(join(claudeConfigDir, "plugins"), { recursive: true });
+  return resolvePluginUpdatePaths({ homeDir, claudeConfigDir });
+}
+
+function writeInstalled(
+  paths: ReturnType<typeof tempPaths>,
+  sha: string,
+  version = "0.2.0",
+): void {
+  writeFileSync(
+    paths.installedPluginsPath,
+    JSON.stringify({
+      version: 2,
+      plugins: {
+        "tui-gamepigeon@tui-gamepigeon": [
+          {
+            scope: "user",
+            version,
+            gitCommitSha: sha,
+            installPath: "/tmp/plugin",
+          },
+        ],
+      },
+    }),
+  );
+}
+
+function writeFlag(
+  paths: ReturnType<typeof tempPaths>,
+  flag: {
+    fromVersion: string;
+    toVersion: string;
+    fromLabel?: string;
+    toLabel?: string;
+    detectedAt?: string;
+  },
+): void {
+  mkdirSync(dirname(paths.flagPath), { recursive: true });
+  writeFileSync(
+    paths.flagPath,
+    JSON.stringify({
+      fromLabel: "0.2.0",
+      toLabel: "0.2.0",
+      detectedAt: "2026-07-19T00:00:00.000Z",
+      ...flag,
+    }),
+  );
+}
+
+function writeMarketplace(
+  paths: ReturnType<typeof tempPaths>,
+  source: { source: string; path?: string; repo?: string },
+): void {
+  writeFileSync(
+    paths.knownMarketplacesPath,
+    JSON.stringify({
+      "tui-gamepigeon": { source },
+    }),
+  );
+}
+
+function mockFetch(remoteVersion: string | null, ok = true, tag?: string): typeof fetch {
+  return (async (input: RequestInfo | URL) => {
+    const url = String(input);
+    if (url.includes("overlay-release.json")) {
+      return {
+        ok: ok && Boolean(remoteVersion),
+        json: async () => (remoteVersion ? { tag: tag ?? `overlay-v${remoteVersion}`, version: remoteVersion } : {}),
+      } as Response;
+    }
+    return { ok: false, json: async () => ({}) } as Response;
+  }) as typeof fetch;
+}
+
+describe("plugin update checker", () => {
+  test("parses check, nudge, and clear actions", () => {
+    expect(parsePluginUpdateAction(["--check"])).toBe("check");
+    expect(parsePluginUpdateAction(["--nudge"])).toBe("nudge");
+    expect(parsePluginUpdateAction(["--clear"])).toBe("clear");
+    expect(parsePluginUpdateAction([])).toBe("check");
+    expect(() => parsePluginUpdateAction(["--unknown"])).toThrow("Unknown plugin-update action");
+  });
+
+  test("skips when GAMEPIGEON_SKIP_UPDATE_CHECK=1", () => {
+    expect(shouldSkipUpdateCheck({ GAMEPIGEON_SKIP_UPDATE_CHECK: "1" })).toBe(true);
+    expect(shouldSkipUpdateCheck({})).toBe(false);
+  });
+
+  test("detects directory marketplaces and reads installed plugin records", () => {
+    const paths = tempPaths();
+    writeMarketplace(paths, { source: "directory", path: "/tmp/local" });
+    expect(isDirectoryMarketplace(paths.knownMarketplacesPath)).toBe(true);
+    writeMarketplace(paths, { source: "github", repo: "Trolleroof/tui-gamepigeon" });
+    expect(isDirectoryMarketplace(paths.knownMarketplacesPath)).toBe(false);
+
+    writeInstalled(paths, "abcdef1234567890");
+    expect(readInstalledPlugin(paths.installedPluginsPath)?.gitCommitSha).toBe("abcdef1234567890");
+  });
+
+  test("writes a flag when the published release manifest version differs from the installed plugin", async () => {
+    const paths = tempPaths();
+    writeMarketplace(paths, { source: "github", repo: "Trolleroof/tui-gamepigeon" });
+    writeInstalled(paths, "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "0.2.0");
+
+    const flag = await runPluginUpdateCheck({
+      paths,
+      request: mockFetch("0.2.2"),
+      now: () => "2026-07-19T00:00:00.000Z",
+    });
+
+    expect(flag).toEqual({
+      fromVersion: "0.2.0",
+      toVersion: "0.2.2",
+      fromLabel: "0.2.0",
+      toLabel: "0.2.2",
+      detectedAt: "2026-07-19T00:00:00.000Z",
+    });
+    expect(readUpdateFlag(paths.flagPath)?.toVersion).toBe("0.2.2");
+    expect(existsSync(paths.statusLinePath)).toBe(true);
+    expect(readFileSync(paths.statusLinePath, "utf8")).toContain("update-available.json");
+  });
+
+  test("clears the flag when the installed plugin matches the published release", async () => {
+    const paths = tempPaths();
+    writeMarketplace(paths, { source: "github", repo: "Trolleroof/tui-gamepigeon" });
+    writeInstalled(paths, "cccccccccccccccccccccccccccccccccccccccc", "0.2.0");
+    writeFlag(paths, { fromVersion: "0.1.9", toVersion: "0.2.0" });
+
+    const flag = await runPluginUpdateCheck({
+      paths,
+      request: mockFetch("0.2.0"),
+    });
+
+    expect(flag).toBeNull();
+    expect(readUpdateFlag(paths.flagPath)).toBeNull();
+  });
+
+  test("does not nudge merely because main's HEAD moved without a published release", async () => {
+    // A version-bump commit landing on main (before the release job finishes
+    // building/publishing) must not trigger a nudge; only overlay-release.json
+    // catching up to the installed version should.
+    const paths = tempPaths();
+    writeMarketplace(paths, { source: "github", repo: "Trolleroof/tui-gamepigeon" });
+    writeInstalled(paths, "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "0.2.0");
+
+    const flag = await runPluginUpdateCheck({
+      paths,
+      request: mockFetch("0.2.0"),
+    });
+
+    expect(flag).toBeNull();
+  });
+
+  test("does not nudge backward when the installed plugin is already ahead of the last published release", async () => {
+    // Simulates the marketplace's own auto-update pulling main HEAD (already
+    // bumped to 0.2.3 locally) while overlay-release.json still points at
+    // the last published 0.2.2 because the 0.2.3 release build is still
+    // running. A plain inequality check would wrongly nudge "0.2.3 → 0.2.2".
+    const paths = tempPaths();
+    writeMarketplace(paths, { source: "github", repo: "Trolleroof/tui-gamepigeon" });
+    writeInstalled(paths, "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "0.2.3");
+
+    const flag = await runPluginUpdateCheck({
+      paths,
+      request: mockFetch("0.2.2"),
+    });
+
+    expect(flag).toBeNull();
+  });
+
+  test("skips directory marketplaces and missing install records", async () => {
+    const paths = tempPaths();
+    writeMarketplace(paths, { source: "directory", path: "/tmp/local" });
+    writeInstalled(paths, "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
+    expect(
+      await runPluginUpdateCheck({
+        paths,
+        request: mockFetch("0.2.2"),
+      }),
+    ).toBeNull();
+
+    const empty = tempPaths();
+    writeMarketplace(empty, { source: "github", repo: "Trolleroof/tui-gamepigeon" });
+    expect(
+      await runPluginUpdateCheck({
+        paths: empty,
+        request: mockFetch("0.2.2"),
+      }),
+    ).toBeNull();
+  });
+
+  test("offline fetch failures are a no-op and leave an existing flag alone", async () => {
+    const paths = tempPaths();
+    writeMarketplace(paths, { source: "github", repo: "Trolleroof/tui-gamepigeon" });
+    writeInstalled(paths, "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
+    writeFlag(paths, { fromVersion: "0.2.0", toVersion: "0.2.1" });
+
+    const flag = await runPluginUpdateCheck({
+      paths,
+      request: mockFetch(null, false),
+      runGhManifest: async () => null,
+    });
+
+    expect(flag).toBeNull();
+    expect(readUpdateFlag(paths.flagPath)?.toVersion).toBe("0.2.1");
+  });
+
+  test("falls back to gh when the public GitHub API cannot see a private repo", async () => {
+    const paths = tempPaths();
+    writeMarketplace(paths, { source: "github", repo: "Trolleroof/tui-gamepigeon" });
+    writeInstalled(paths, "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "0.2.0");
+
+    const flag = await runPluginUpdateCheck({
+      paths,
+      request: mockFetch(null, false),
+      runGhManifest: async () => ({ tag: "overlay-v0.2.2", version: "0.2.2" }),
+      now: () => "2026-07-19T00:00:00.000Z",
+    });
+
+    expect(flag?.fromVersion).toBe("0.2.0");
+    expect(flag?.toVersion).toBe("0.2.2");
+    expect(readUpdateFlag(paths.flagPath)?.toVersion).toBe("0.2.2");
+  });
+
+  test("skips checks when GAMEPIGEON_SKIP_UPDATE_CHECK is set", async () => {
+    const paths = tempPaths();
+    writeMarketplace(paths, { source: "github", repo: "Trolleroof/tui-gamepigeon" });
+    writeInstalled(paths, "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
+
+    const flag = await runPluginUpdateCheck({
+      paths,
+      env: { GAMEPIGEON_SKIP_UPDATE_CHECK: "1" },
+      request: mockFetch("0.2.2"),
+    });
+
+    expect(flag).toBeNull();
+    expect(readUpdateFlag(paths.flagPath)).toBeNull();
+    expect(existsSync(paths.statusLinePath)).toBe(true);
+  });
+
+  test("nudge emits hookSpecificOutput JSON when a flag is present", () => {
+    const paths = tempPaths();
+    writeFlag(paths, { fromVersion: "0.2.0", toVersion: "0.2.1", fromLabel: "0.2.0", toLabel: "0.2.1" });
+
+    const output = runPluginUpdateNudge(paths);
+    expect(output).toBeTruthy();
+    const parsed = JSON.parse(output!);
+    expect(parsed.hookSpecificOutput.hookEventName).toBe("UserPromptSubmit");
+    expect(parsed.hookSpecificOutput.additionalContext).toContain("/tui-gamepigeon:arcade-update");
+    expect(parsed.hookSpecificOutput.additionalContext).toContain("(0.2.1)");
+
+    runPluginUpdateClear(paths);
+    expect(runPluginUpdateNudge(paths)).toBeNull();
+  });
+
+  test("status-line shim and nudge helper use subdued version labels", () => {
+    const paths = tempPaths();
+    writeStatusLineShim(paths.statusLinePath, paths.flagPath);
+    const script = readFileSync(paths.statusLinePath, "utf8");
+    expect(script).toContain("update available");
+    expect(script).toContain("\\u001b[90m"); // muted gray
+    expect(script).not.toContain(">>>");
+    const line = formatUpdateStatusLine("0.2.0", "0.2.2");
+    expect(line).toContain("Arcade");
+    expect(line).toContain("0.2.0");
+    expect(line).toContain("0.2.2");
+    expect(line).toContain("update available");
+    expect(line).not.toContain(">>>");
+    expect(line).not.toContain("/tui-gamepigeon:arcade-update");
+    const nudge = nudgeHookOutput({
+      fromVersion: "0.2.0",
+      toVersion: "0.2.2",
+      fromLabel: "0.2.0",
+      toLabel: "0.2.2",
+      detectedAt: "2026-07-19T00:00:00.000Z",
+    });
+    expect(nudge).toContain("An update is available (0.2.2)");
+    expect(nudge).toContain("/tui-gamepigeon:arcade-update");
+  });
+
+  test("fetchRemoteReleaseManifest reads overlay-release.json from main", async () => {
+    const manifest = await fetchRemoteReleaseManifest("Trolleroof/tui-gamepigeon", mockFetch("0.2.3"));
+    expect(manifest).toEqual({ tag: "overlay-v0.2.3", version: "0.2.3" });
+  });
+
+  test("formatUpdateVersions prefers labels", () => {
+    expect(formatUpdateVersions({
+      fromVersion: "ignored",
+      toVersion: "ignored",
+      fromLabel: "0.2.0",
+      toLabel: "0.2.2",
+      detectedAt: "2026-07-19T00:00:00.000Z",
+    })).toEqual({ from: "0.2.0", to: "0.2.2" });
+  });
+});

package/scripts/plugin-update.ts

@@ -0,0 +1,378 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { repoSlug, type ReleaseManifest } from "./overlay.js";
+
+export type PluginUpdateAction = "check" | "nudge" | "clear";
+
+export interface UpdateAvailableFlag {
+  fromVersion: string;
+  toVersion: string;
+  fromLabel: string;
+  toLabel: string;
+  detectedAt: string;
+}
+
+export interface InstalledPluginRecord {
+  gitCommitSha?: string;
+  version?: string;
+  installPath?: string;
+  scope?: string;
+}
+
+export interface MarketplaceSource {
+  source: string;
+  path?: string;
+  repo?: string;
+}
+
+export interface PluginUpdatePaths {
+  homeDir: string;
+  claudeConfigDir: string;
+  flagPath: string;
+  statusLinePath: string;
+  installedPluginsPath: string;
+  knownMarketplacesPath: string;
+}
+
+const ROOT_DIR = join(dirname(fileURLToPath(import.meta.url)), "..");
+const PLUGIN_KEY = "tui-gamepigeon@tui-gamepigeon";
+const MARKETPLACE_NAME = "tui-gamepigeon";
+type FetchLike = typeof fetch;
+
+/** Muted terminal palette aligned with overlay tokens (--muted, --ink, --accent). */
+const STATUS = {
+  reset: "\x1b[0m",
+  muted: "\x1b[90m",
+  ink: "\x1b[37m",
+  accent: "\x1b[33m",
+} as const;
+
+export function parsePluginUpdateAction(args: string[]): PluginUpdateAction {
+  const value = args[0] ?? "--check";
+  if (value === "--check") return "check";
+  if (value === "--nudge") return "nudge";
+  if (value === "--clear") return "clear";
+  throw new Error(`Unknown plugin-update action: ${value}`);
+}
+
+export function gamepigeonHome(home = homedir()): string {
+  return process.env.GAMEPIGEON_HOME ?? join(home, ".gamepigeon");
+}
+
+export function resolvePluginUpdatePaths(options: {
+  homeDir?: string;
+  claudeConfigDir?: string;
+} = {}): PluginUpdatePaths {
+  const homeDir = options.homeDir ?? homedir();
+  const claudeConfigDir = options.claudeConfigDir ?? process.env.CLAUDE_CONFIG_DIR ?? join(homeDir, ".claude");
+  // Explicit homeDir (tests) always nests under that tree; production uses GAMEPIGEON_HOME or ~/.gamepigeon.
+  const home = options.homeDir !== undefined ? join(homeDir, ".gamepigeon") : gamepigeonHome(homeDir);
+  return {
+    homeDir,
+    claudeConfigDir,
+    flagPath: join(home, "update-available.json"),
+    statusLinePath: join(home, "status-line.ts"),
+    installedPluginsPath: join(claudeConfigDir, "plugins", "installed_plugins.json"),
+    knownMarketplacesPath: join(claudeConfigDir, "plugins", "known_marketplaces.json"),
+  };
+}
+
+export function readUpdateFlag(flagPath: string): UpdateAvailableFlag | null {
+  try {
+    const parsed = JSON.parse(readFileSync(flagPath, "utf8"));
+    if (
+      typeof parsed.fromVersion === "string" &&
+      typeof parsed.toVersion === "string" &&
+      typeof parsed.fromLabel === "string" &&
+      typeof parsed.toLabel === "string" &&
+      typeof parsed.detectedAt === "string"
+    ) {
+      return parsed as UpdateAvailableFlag;
+    }
+  } catch {
+    // Missing or malformed flag means no update nudge.
+  }
+  return null;
+}
+
+export function writeUpdateFlag(flagPath: string, flag: UpdateAvailableFlag): void {
+  mkdirSync(dirname(flagPath), { recursive: true });
+  writeFileSync(flagPath, `${JSON.stringify(flag, null, 2)}\n`, { mode: 0o600 });
+}
+
+export function clearUpdateFlag(flagPath: string): void {
+  try {
+    rmSync(flagPath, { force: true });
+  } catch {
+    // Best-effort cleanup.
+  }
+}
+
+export function readPackageVersion(root = ROOT_DIR): string {
+  try {
+    const parsed = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    if (typeof parsed.version === "string") return parsed.version;
+  } catch {
+    // Fall through.
+  }
+  return "unknown";
+}
+
+export function readInstalledPlugin(
+  installedPluginsPath: string,
+  pluginKey = PLUGIN_KEY,
+): InstalledPluginRecord | null {
+  try {
+    const parsed = JSON.parse(readFileSync(installedPluginsPath, "utf8"));
+    const entries = parsed?.plugins?.[pluginKey];
+    if (!Array.isArray(entries) || entries.length === 0) return null;
+    const record = entries[0];
+    if (!record || typeof record !== "object") return null;
+    return record as InstalledPluginRecord;
+  } catch {
+    return null;
+  }
+}
+
+export function isDirectoryMarketplace(
+  knownMarketplacesPath: string,
+  marketplaceName = MARKETPLACE_NAME,
+): boolean {
+  try {
+    const parsed = JSON.parse(readFileSync(knownMarketplacesPath, "utf8"));
+    const source = parsed?.[marketplaceName]?.source as MarketplaceSource | undefined;
+    return source?.source === "directory";
+  } catch {
+    return false;
+  }
+}
+
+export function shouldSkipUpdateCheck(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.GAMEPIGEON_SKIP_UPDATE_CHECK === "1";
+}
+
+export type GhManifestRunner = (slug: string) => Promise<ReleaseManifest | null>;
+
+async function fetchRemoteReleaseManifestViaGh(slug: string): Promise<ReleaseManifest | null> {
+  try {
+    const proc = Bun.spawn(["gh", "api", `repos/${slug}/contents/overlay-release.json`, "--jq", ".content"], {
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+    const encoded = (await new Response(proc.stdout).text()).trim();
+    if ((await proc.exited) !== 0 || !encoded) return null;
+    const parsed = JSON.parse(Buffer.from(encoded, "base64").toString("utf8")) as Partial<ReleaseManifest>;
+    if (typeof parsed.tag === "string" && typeof parsed.version === "string") {
+      return { tag: parsed.tag, version: parsed.version };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the latest *published* release, i.e. `overlay-release.json` on main.
+ * That file is only committed once the `overlay.yml` release job has finished
+ * building both platform binaries and created the GitHub release — unlike
+ * `package.json`'s version, which lands on main as soon as the version-bump
+ * commit is pushed, well before CI has built or released anything. Comparing
+ * against the version bump would nudge users to update before a release even
+ * exists to download.
+ */
+export async function fetchRemoteReleaseManifest(
+  slug: string,
+  request: FetchLike = fetch,
+  runGh: GhManifestRunner = fetchRemoteReleaseManifestViaGh,
+): Promise<ReleaseManifest | null> {
+  try {
+    const response = await request(`https://raw.githubusercontent.com/${slug}/main/overlay-release.json`, {
+      headers: { "User-Agent": "tui-gamepigeon-plugin-update" },
+    });
+    if (response.ok) {
+      const parsed = (await response.json()) as Partial<ReleaseManifest>;
+      if (typeof parsed.tag === "string" && typeof parsed.version === "string") {
+        return { tag: parsed.tag, version: parsed.version };
+      }
+    }
+  } catch {
+    // Fall through to gh for private repos.
+  }
+  return runGh(slug);
+}
+
+/**
+ * Compares dotted numeric versions (e.g. "0.2.3" vs "0.2.10"). Returns
+ * positive if `a` > `b`, negative if `a` < `b`, 0 if equal or unparsable.
+ */
+export function compareVersions(a: string, b: string): number {
+  const partsA = a.split(".").map((n) => Number.parseInt(n, 10));
+  const partsB = b.split(".").map((n) => Number.parseInt(n, 10));
+  const length = Math.max(partsA.length, partsB.length);
+  for (let i = 0; i < length; i++) {
+    const numA = partsA[i] ?? 0;
+    const numB = partsB[i] ?? 0;
+    if (Number.isNaN(numA) || Number.isNaN(numB)) return 0;
+    if (numA !== numB) return numA - numB;
+  }
+  return 0;
+}
+
+export function formatUpdateVersions(flag: UpdateAvailableFlag): { from: string; to: string } {
+  return {
+    from: flag.fromLabel || flag.fromVersion,
+    to: flag.toLabel || flag.toVersion,
+  };
+}
+
+/** Subdued status-line text for an available plugin update (ASCII-safe for terminals). */
+export function formatUpdateStatusLine(fromVersion: string, toVersion: string): string {
+  const { reset, muted, ink, accent } = STATUS;
+  return (
+    `${muted}Arcade${reset} ` +
+    `${ink}${fromVersion}${reset}` +
+    `${muted} → ${reset}` +
+    `${accent}${toVersion}${reset} ` +
+    `${muted}update available${reset}`
+  );
+}
+
+export function statusLineScriptSource(flagPath: string): string {
+  return `#!/usr/bin/env bun
+import { readFileSync } from "node:fs";
+
+const FLAG_PATH = ${JSON.stringify(flagPath)};
+const A = ${JSON.stringify(STATUS)};
+
+try {
+  const flag = JSON.parse(readFileSync(FLAG_PATH, "utf8"));
+  const from = flag?.fromLabel || flag?.fromVersion;
+  const to = flag?.toLabel || flag?.toVersion;
+  if (typeof from === "string" && typeof to === "string") {
+    process.stdout.write(
+      A.muted + "Arcade" + A.reset + " " +
+      A.ink + from + A.reset +
+      A.muted + " → " + A.reset +
+      A.accent + to + A.reset + " " +
+      A.muted + "update available" + A.reset
+    );
+    process.exit(0);
+  }
+} catch {
+  // No update flag.
+}
+process.stdout.write("");
+`;
+}
+
+export function writeStatusLineShim(statusLinePath: string, flagPath: string): void {
+  mkdirSync(dirname(statusLinePath), { recursive: true });
+  writeFileSync(statusLinePath, statusLineScriptSource(flagPath), { mode: 0o755 });
+}
+
+export function nudgeHookOutput(flag: UpdateAvailableFlag): string {
+  const { to } = formatUpdateVersions(flag);
+  const additionalContext =
+    `An update is available (${to}). Run this command: /tui-gamepigeon:arcade-update`;
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "UserPromptSubmit",
+      additionalContext,
+    },
+  });
+}
+
+export async function runPluginUpdateCheck(options: {
+  paths?: PluginUpdatePaths;
+  root?: string;
+  request?: FetchLike;
+  runGhManifest?: GhManifestRunner;
+  env?: NodeJS.ProcessEnv;
+  now?: () => string;
+}): Promise<UpdateAvailableFlag | null> {
+  const env = options.env ?? process.env;
+  const paths = options.paths ?? resolvePluginUpdatePaths();
+  const root = options.root ?? ROOT_DIR;
+  const now = options.now ?? (() => new Date().toISOString());
+
+  writeStatusLineShim(paths.statusLinePath, paths.flagPath);
+
+  if (shouldSkipUpdateCheck(env)) return null;
+  if (isDirectoryMarketplace(paths.knownMarketplacesPath)) return null;
+
+  const installed = readInstalledPlugin(paths.installedPluginsPath);
+  if (!installed?.gitCommitSha) return null;
+
+  const slug = repoSlug(root);
+  // Compare against the published release manifest, not main's HEAD sha or
+  // package.json — those move the instant a version-bump commit lands on
+  // main, long before CI has finished building and releasing that version.
+  const remoteManifest = await fetchRemoteReleaseManifest(
+    slug,
+    options.request ?? fetch,
+    options.runGhManifest ?? fetchRemoteReleaseManifestViaGh,
+  );
+  if (!remoteManifest) return null;
+
+  const installedVersion = typeof installed.version === "string" ? installed.version : readPackageVersion(root);
+  const remoteVersion = remoteManifest.version;
+
+  // Only nudge when the published release is strictly newer. The plugin
+  // marketplace's own auto-update can pull main HEAD (including an
+  // unreleased version bump) ahead of the last published release, so
+  // equality isn't enough here — a plain "!==" would fire a nudge pointing
+  // users backward to an older release while a build is still in flight.
+  if (compareVersions(remoteVersion, installedVersion) <= 0) {
+    clearUpdateFlag(paths.flagPath);
+    return null;
+  }
+
+  const flag: UpdateAvailableFlag = {
+    fromVersion: installedVersion,
+    toVersion: remoteVersion,
+    fromLabel: installedVersion,
+    toLabel: remoteVersion,
+    detectedAt: now(),
+  };
+  writeUpdateFlag(paths.flagPath, flag);
+  return flag;
+}
+
+export function runPluginUpdateNudge(paths: PluginUpdatePaths = resolvePluginUpdatePaths()): string | null {
+  const flag = readUpdateFlag(paths.flagPath);
+  if (!flag) return null;
+  return nudgeHookOutput(flag);
+}
+
+export function runPluginUpdateClear(paths: PluginUpdatePaths = resolvePluginUpdatePaths()): void {
+  clearUpdateFlag(paths.flagPath);
+}
+
+export async function main(args = process.argv.slice(2)): Promise<void> {
+  const action = parsePluginUpdateAction(args);
+  const paths = resolvePluginUpdatePaths();
+
+  if (action === "clear") {
+    runPluginUpdateClear(paths);
+    return;
+  }
+
+  if (action === "nudge") {
+    const output = runPluginUpdateNudge(paths);
+    if (output) process.stdout.write(`${output}\n`);
+    return;
+  }
+
+  await runPluginUpdateCheck({ paths });
+}
+
+if (import.meta.main) {
+  try {
+    await main();
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}