commandmate 0.10.3 → 0.10.4

package/dist/server/src/lib/db/migrations/v43-remove-cm-root-dir-ghost-repository.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * Migration v43: delete the CM_ROOT_DIR ghost repository row (Issue #1339).
+ *
+ * Before #1328, `getRepositoryPaths()` returned CM_ROOT_DIR as if it were a
+ * single repository path, and the sync route handed it to
+ * `ensureEnvRepositoriesRegistered()`, which wrote it to `repositories` with
+ * `is_env_managed = 1`. But CM_ROOT_DIR is the *container* of repositories, not
+ * a repository: `git worktree list` run there returns nothing, so no `worktrees`
+ * row was ever created for it. The result is a repository row with no worktrees
+ * under it — visible in the repository management screen, absent from the
+ * sidebar (which is driven by `worktrees`), and impossible for the user to tell
+ * apart from a real entry.
+ *
+ * #1328 removed the discovery that created these rows but deliberately left the
+ * existing rows alone. This migration is that clean-up.
+ *
+ * SCOPE: only the `is_env_managed = 1` row whose path is exactly CM_ROOT_DIR.
+ * The `is_env_managed = 0` ghosts written by `disableRepository()` are a
+ * different defect (#1346) and are not touched here.
+ *
+ * The three guards below exist because deleting a *legitimate* env-managed row
+ * is not a harmless mistake: `ensureEnvRepositoriesRegistered()` recreates a
+ * missing row with `enabled: true` (db-repository.ts:469), so a wrong delete
+ * silently re-enables a repository the user had switched off, and drops their
+ * `visible` / `display_name` alongside it. Every guard fails toward keeping the
+ * row.
+ *
+ * Backward compatibility: a DB with no ghost row (the normal case for anyone who
+ * never ran a pre-#1328 build) matches nothing and the migration is a no-op.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.v43_migrations = void 0;
+const path_1 = __importDefault(require("path"));
+/**
+ * The configured CM_ROOT_DIR, resolved the same way the ghost row's path was
+ * written: `path.resolve()` over the raw env value (`resolveRepositoryPath()`).
+ *
+ * Deliberately NOT `getEnv()`: that falls back to `process.cwd()` when
+ * CM_ROOT_DIR is unset (env.ts:218), which would aim this DELETE at whatever
+ * directory the server happened to start in — quite plausibly a real repository.
+ * An unset CM_ROOT_DIR must mean "skip", never "target cwd".
+ *
+ * Read straight from process.env rather than through env.ts so the migration
+ * stays frozen: it must keep deleting exactly what the pre-#1328 code wrote,
+ * whatever env.ts grows into later.
+ *
+ * @returns Resolved CM_ROOT_DIR, or null when it is not configured
+ */
+function getConfiguredRootDir() {
+    // MCBD_ROOT_DIR is the pre-#76 name and still supported (env.ts ENV_MAPPING).
+    const raw = process.env.CM_ROOT_DIR ?? process.env.MCBD_ROOT_DIR;
+    if (!raw || !raw.trim()) {
+        return null;
+    }
+    return path_1.default.resolve(raw.trim());
+}
+/**
+ * WORKTREE_REPOS entries, resolved. These are the *legitimate* `is_env_managed`
+ * rows: post-#1328 `getRepositoryPaths()` returns this list and nothing else.
+ *
+ * Parsed inline, mirroring `getRepositoryPaths()` (git/worktrees.ts:144), rather
+ * than imported: worktrees.ts pulls in `@/lib/db`, whose barrel re-exports this
+ * very migration list.
+ *
+ * @returns Resolved WORKTREE_REPOS paths (empty when unset)
+ */
+function getWorktreeRepoPaths() {
+    const raw = process.env.WORKTREE_REPOS;
+    if (!raw || !raw.trim()) {
+        return [];
+    }
+    return raw
+        .split(',')
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0)
+        .map((p) => path_1.default.resolve(p));
+}
+exports.v43_migrations = [
+    {
+        version: 43,
+        name: 'remove-cm-root-dir-ghost-repository',
+        up: (db) => {
+            // Guard 1: no CM_ROOT_DIR, no target. See getConfiguredRootDir().
+            const rootDir = getConfiguredRootDir();
+            if (!rootDir) {
+                console.log('Migration 43: CM_ROOT_DIR is not set; no ghost row to remove');
+                return;
+            }
+            // Guard 2: CM_ROOT_DIR may legitimately also be listed in WORKTREE_REPOS,
+            // which makes its is_env_managed row real and its absence self-healing at
+            // enabled=true. Never delete a row the env still asks for.
+            if (getWorktreeRepoPaths().includes(rootDir)) {
+                console.log(`Migration 43: ${rootDir} is a WORKTREE_REPOS entry; keeping its repository row`);
+                return;
+            }
+            // Guard 3 (the NOT EXISTS): a row with worktrees under it is not a ghost,
+            // whatever the env says. This is the condition the issue names, and it is
+            // what makes the delete provably lossless — nothing references the row.
+            const result = db
+                .prepare(`DELETE FROM repositories
+            WHERE path = ?
+              AND is_env_managed = 1
+              AND NOT EXISTS (
+                SELECT 1 FROM worktrees WHERE worktrees.repository_path = ?
+              )`)
+                .run(rootDir, rootDir);
+            if (result.changes > 0) {
+                console.log(`Migration 43: removed CM_ROOT_DIR ghost repository row (${rootDir})`);
+            }
+            else {
+                console.log(`Migration 43: no ghost repository row at ${rootDir}`);
+            }
+        },
+        down: () => {
+            // The deleted row carried no user data — an env-managed ghost with no
+            // worktrees, no clone URL, and default flags — and re-inserting it would
+            // restore the very defect this migration fixes. No-op rollback (mirrors
+            // v35/v40).
+            console.log('No rollback for the CM_ROOT_DIR ghost row removal');
+        },
+    },
+];

package/dist/server/src/lib/git/worktrees.js

@@ -13,8 +13,11 @@ exports.getRepositoryPaths = getRepositoryPaths;
 exports.scanWorktrees = scanWorktrees;
 exports.scanMultipleRepositories = scanMultipleRepositories;
 exports.syncWorktreesToDB = syncWorktreesToDB;
+exports.repositoryExistsOnDisk = repositoryExistsOnDisk;
+exports.pruneStaleRepositoryWorktrees = pruneStaleRepositoryWorktrees;
 const child_process_1 = require("child_process");
 const util_1 = require("util");
+const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const db_1 = require("../../lib/db");
 const logger_1 = require("../../lib/logger");
@@ -293,3 +296,90 @@ function syncWorktreesToDB(db, worktrees) {
     }
     return { deletedIds: allDeletedIds, upsertedCount };
 }
+/**
+ * Whether a repository still exists on disk as a git working tree.
+ *
+ * Returns `false` only when the directory itself is gone OR its `.git` entry is
+ * missing (a de-gitified directory). Every other state — including a present
+ * directory whose `.git` is intact — is reported as "still there", so a
+ * transient git failure (a locked index, a momentarily-unavailable network
+ * drive whose mount point is still present, …) never satisfies the prune
+ * condition. Issue #1349: fall on the side of NOT pruning whenever the on-disk
+ * state is inconclusive.
+ *
+ * @param repoPath - Canonical repository path (as stored in
+ *   `worktrees.repository_path`, i.e. already `path.resolve()`d by
+ *   {@link scanWorktrees}; see #1347)
+ * @returns `true` if the repository still looks present on disk
+ */
+function repositoryExistsOnDisk(repoPath) {
+    if (!repoPath)
+        return false;
+    try {
+        return fs_1.default.existsSync(repoPath) && fs_1.default.existsSync(path_1.default.join(repoPath, '.git'));
+    }
+    catch {
+        // Inconclusive filesystem read (e.g. EACCES): be conservative and keep rows.
+        return true;
+    }
+}
+/**
+ * Prune DB worktree rows for repositories that have vanished from disk.
+ *
+ * Issue #1349: when a repository directory is deleted or de-gitified,
+ * {@link scanWorktrees} returns `[]` (git exit 128), so the repository silently
+ * drops out of the scan and {@link syncWorktreesToDB} never reaches its per-repo
+ * prune for it — the rows linger as ghost entries in the sidebar. The global
+ * early-return in `syncWorktreesToDB` only fires when *every* repository is
+ * empty, so a single vanished repository among healthy ones is never cleaned up.
+ *
+ * This runs as the global-sync reconciliation step: it enumerates every
+ * `repository_path` that still owns worktree rows and, for those that produced
+ * no worktrees in the current scan, deletes the rows **only when the repository
+ * directory (or its `.git`) is genuinely gone** (see
+ * {@link repositoryExistsOnDisk}). A repository that still exists but merely
+ * errored in git is left untouched, so a transient failure — a network drive
+ * blip, a locked repo — never destroys history.
+ *
+ * Intended for the full-scan endpoint (`POST /api/repositories/sync`) only.
+ * Single-repository callers (scan/restore) must NOT run this: they hold no
+ * authority over repositories outside their own scan, and running it there would
+ * prune repositories that merely weren't part of that request.
+ *
+ * Row keys stay consistent with #1347: {@link getRepositories} returns the
+ * stored (already `path.resolve()`d) `repository_path`, and every subsequent DB
+ * and filesystem lookup uses that same canonical value.
+ *
+ * @param db - Database instance
+ * @param liveWorktrees - Worktrees produced by the current scan; their
+ *   repositories are known-present and therefore skipped
+ * @returns IDs of worktrees deleted for vanished repositories
+ */
+function pruneStaleRepositoryWorktrees(db, liveWorktrees) {
+    // Repositories that produced at least one worktree this scan are alive by
+    // definition (git listed them), so they are never candidates for pruning.
+    const liveRepoPaths = new Set(liveWorktrees
+        .map(wt => wt.repositoryPath)
+        .filter((p) => !!p));
+    const deletedIds = [];
+    for (const repo of (0, db_1.getRepositories)(db)) {
+        const repoPath = repo.path;
+        if (!repoPath)
+            continue;
+        if (liveRepoPaths.has(repoPath))
+            continue;
+        // Conservative guard: keep rows unless the directory/.git is truly gone.
+        if (repositoryExistsOnDisk(repoPath))
+            continue;
+        const ids = (0, db_1.getWorktreesByRepository)(db, repoPath).map(row => row.id);
+        if (ids.length === 0)
+            continue;
+        const result = (0, db_1.deleteWorktreesByIds)(db, ids);
+        deletedIds.push(...ids);
+        logger.info('worktree:stale-repo-pruned', {
+            repoPath,
+            deletedCount: result.deletedCount,
+        });
+    }
+    return deletedIds;
+}

package/dist/server/src/lib/job-executor.js

@@ -136,8 +136,12 @@ async function executeSchedule(state) {
         return;
     }
     state.isExecuting = true;
-    const logId = createExecutionLog(state.scheduleId, state.worktreeId, state.entry.message);
+    // Issue #1343: createExecutionLog() must stay inside the try so that a DB
+    // failure still reaches the finally that resets isExecuting. Otherwise the
+    // schedule is skipped by the guard above until the server restarts.
+    let logId;
     try {
+        logId = createExecutionLog(state.scheduleId, state.worktreeId, state.entry.message);
         const db = getLazyDbInstance();
         const worktree = db.prepare('SELECT path, vibe_local_model FROM worktrees WHERE id = ?').get(state.worktreeId);
         if (!worktree) {
@@ -153,7 +157,9 @@ async function executeSchedule(state) {
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
-        updateExecutionLog(logId, 'failed', errorMessage, null);
+        if (logId !== undefined) {
+            updateExecutionLog(logId, 'failed', errorMessage, null);
+        }
         logger.error('execution:failed', { name: state.entry.name, error: errorMessage });
     }
     finally {

package/dist/server/src/lib/realtime/types.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * Realtime (WebSocket) message contracts shared by the server broadcasters and
+ * the client consumers. Issue #1120.
+ *
+ * Server broadcasts are double-wrapped by `handleBroadcast` into an envelope:
+ *   { type: 'broadcast', worktreeId, data: { type: '<realType>', ...payload } }
+ * `parseRealtimeEvent` unwraps that envelope and returns the inner payload as
+ * the canonical {@link RealtimeEvent}.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION_MISMATCH_EVENT_TYPE = exports.CLIENT_VERSION_MESSAGE_TYPE = void 0;
+exports.isVersionMismatch = isVersionMismatch;
+exports.parseRealtimeEvent = parseRealtimeEvent;
+/**
+ * Client → server hello carrying the client bundle version, sent on every
+ * (re)connect so the server can detect a version drift (#1356). Kept as a shared
+ * constant so the client sender and the server handler cannot drift apart.
+ */
+exports.CLIENT_VERSION_MESSAGE_TYPE = 'client_version';
+/**
+ * Server → client notice that the running server version differs from this
+ * tab's bundle version (#1338/#1356). Drives the reload banner.
+ */
+exports.VERSION_MISMATCH_EVENT_TYPE = 'version_mismatch';
+/**
+ * Whether the running server version and this tab's bundle version have drifted
+ * apart and the user should be nudged to reload (#1338/#1356).
+ *
+ * Conservative on purpose (受入条件: 版が一致している間は誤検知しない): an empty or
+ * `'0.0.0'` fallback on either side means "version unknown" and is never treated
+ * as a mismatch, so a server that cannot resolve its own version stays silent.
+ */
+function isVersionMismatch(serverVersion, clientVersion) {
+    if (!serverVersion || !clientVersion)
+        return false;
+    if (serverVersion === '0.0.0' || clientVersion === '0.0.0')
+        return false;
+    return serverVersion !== clientVersion;
+}
+/**
+ * Parse a raw WebSocket frame into the inner realtime event.
+ *
+ * Handles both the room broadcast envelope ({ type:'broadcast', data:{...} })
+ * and (defensively) already-unwrapped frames. Returns null on malformed input
+ * or frames without a usable inner `type`.
+ */
+function parseRealtimeEvent(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const env = parsed;
+    if (env.type === 'broadcast') {
+        const inner = env.data;
+        if (!inner || typeof inner !== 'object')
+            return null;
+        const innerObj = inner;
+        if (typeof innerObj.type !== 'string')
+            return null;
+        // Ensure worktreeId is present even if the payload omitted it.
+        if (innerObj.worktreeId === undefined && typeof env.worktreeId === 'string') {
+            innerObj.worktreeId = env.worktreeId;
+        }
+        return innerObj;
+    }
+    if (typeof env.type === 'string') {
+        return env;
+    }
+    return null;
+}

package/dist/server/src/lib/schedule-manager.js

@@ -71,7 +71,15 @@ function createScheduleState(worktreeId, scheduleId, entry) {
         entry,
     };
     cronJob.schedule(() => {
-        void (0, job_executor_1.executeSchedule)(state);
+        // Issue #1343: executeSchedule() rejects if its own error handling fails
+        // (e.g. the DB is still down when writing the 'failed' log). Without this
+        // catch the rejection is silently unhandled.
+        void (0, job_executor_1.executeSchedule)(state).catch((error) => {
+            logger.error('execution:unhandled', {
+                name: entry.name,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        });
     });
     return state;
 }

package/dist/server/src/lib/version-checker.js

@@ -0,0 +1,297 @@
+"use strict";
+/**
+ * Version Checker Module
+ * Issue #257: Version update notification feature
+ *
+ * Checks GitHub Releases API for newer versions of CommandMate.
+ * Uses globalThis cache pattern (auto-yes-manager.ts reference) for
+ * hot-reload persistence.
+ *
+ * Security:
+ * - [SEC-001] GITHUB_API_URL is hardcoded (SSRF prevention, OWASP A10:2021)
+ * - [SEC-SF-001] Response validation (validateReleaseUrl, sanitizeReleaseName)
+ * - [SEC-SF-002] User-Agent header for GitHub API compliance (OWASP A07:2021)
+ *
+ * @module version-checker
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GITHUB_RELEASE_URL_PREFIX = exports.GITHUB_API_URL = void 0;
+exports.isNewerVersion = isNewerVersion;
+exports.getClientVersion = getClientVersion;
+exports.getServerVersion = getServerVersion;
+exports.getCurrentVersion = getCurrentVersion;
+exports.validateReleaseUrl = validateReleaseUrl;
+exports.sanitizeReleaseName = sanitizeReleaseName;
+exports.checkForUpdate = checkForUpdate;
+exports.resetCacheForTesting = resetCacheForTesting;
+const fs_1 = require("fs");
+const path_1 = require("path");
+// =============================================================================
+// Constants
+// =============================================================================
+/**
+ * [SEC-001] SSRF Prevention: GitHub API URL is a hardcoded constant.
+ * This value MUST NOT be derived from environment variables, config files,
+ * or user input. Changing this value requires security review.
+ * OWASP A10:2021 - Server-Side Request Forgery
+ */
+exports.GITHUB_API_URL = 'https://api.github.com/repos/Kewton/CommandMate/releases/latest';
+/**
+ * [SEC-SF-001] GitHub Releases URL allowed prefix for validation.
+ * Used to verify html_url from API responses.
+ * Imported from github-links.ts (Issue #264 DRY) and re-exported for backward compatibility.
+ */
+const github_links_1 = require("../config/github-links");
+Object.defineProperty(exports, "GITHUB_RELEASE_URL_PREFIX", { enumerable: true, get: function () { return github_links_1.GITHUB_RELEASE_URL_PREFIX; } });
+/** Semver pattern: optional v-prefix followed by major.minor.patch */
+const SEMVER_PATTERN = /^v?\d+\.\d+\.\d+$/;
+/** [SEC-SF-001] Release name allowed characters pattern */
+const RELEASE_NAME_PATTERN = /^[a-zA-Z0-9.\-\s_v]+$/;
+/** Maximum allowed release name length */
+const RELEASE_NAME_MAX_LENGTH = 128;
+/** Cache TTL: 1 hour (matches GitHub API unauthenticated rate limit of 60 req/h) */
+const CACHE_TTL_MS = 60 * 60 * 1000;
+/** Fetch timeout: 5 seconds */
+const FETCH_TIMEOUT_MS = 5000;
+/**
+ * npm package name. [Issue #1359] Used to verify that a package.json resolved at
+ * runtime is CommandMate's own manifest and not an unrelated project's — a guard
+ * against an unexpected process.cwd() (e.g. a dev run started from a user's
+ * project directory) leaking a foreign version.
+ */
+const PACKAGE_NAME = 'commandmate';
+const cache = globalThis.__versionCheckCache ??
+    (globalThis.__versionCheckCache = {
+        result: null,
+        fetchedAt: 0,
+        rateLimitResetAt: null,
+    });
+// =============================================================================
+// Public Functions
+// =============================================================================
+/**
+ * Compare two semver version strings.
+ * [SF-003] Includes built-in validation - returns false for invalid formats.
+ *
+ * @param current - Current version (e.g., "0.2.3", "v0.2.3")
+ * @param latest - Latest version (e.g., "0.3.0", "v0.3.0")
+ * @returns true if latest is newer than current, false for invalid formats
+ */
+function isNewerVersion(current, latest) {
+    // [SF-003] Defensive validation: reject invalid formats immediately
+    if (!SEMVER_PATTERN.test(current) || !SEMVER_PATTERN.test(latest)) {
+        return false;
+    }
+    const parse = (v) => v.replace(/^v/, '').split('.').map(Number);
+    const [cMajor, cMinor, cPatch] = parse(current);
+    const [lMajor, lMinor, lPatch] = parse(latest);
+    if (lMajor !== cMajor)
+        return lMajor > cMajor;
+    if (lMinor !== cMinor)
+        return lMinor > cMinor;
+    return lPatch > cPatch;
+}
+/**
+ * Read CommandMate's version from the installed package.json at runtime.
+ *
+ * [Issue #1359] `NEXT_PUBLIC_APP_VERSION` is baked into the bundle at
+ * `next build` time, so it reflects "the version present when the client bundle
+ * was last built", not the version of the server code actually running. Reading
+ * package.json on each call reflects the real installed version, which is what
+ * the update-check API must report as `currentVersion`.
+ *
+ * The server is spawned with cwd = package root (start.ts), so
+ * `process.cwd()/package.json` is the installed manifest. We verify
+ * `name === 'commandmate'` so an unexpected cwd can never leak an unrelated
+ * project's version; on any mismatch or read failure the caller falls back to
+ * the baked value.
+ *
+ * @returns Runtime version string, or null when unreadable / not CommandMate's package.json
+ */
+function readRuntimeServerVersion() {
+    try {
+        const raw = (0, fs_1.readFileSync)((0, path_1.join)(process.cwd(), 'package.json'), 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed.name === PACKAGE_NAME &&
+            typeof parsed.version === 'string' &&
+            parsed.version.length > 0) {
+            return parsed.version;
+        }
+        return null;
+    }
+    catch {
+        // Unreadable / malformed package.json: fall back to the baked value.
+        return null;
+    }
+}
+/**
+ * Get the client bundle version (baked at build time).
+ * [CONS-002] `NEXT_PUBLIC_APP_VERSION` is injected by next.config.js from
+ * package.json at `next build` time. This is the correct value to describe
+ * "the version of the bundle this page was served from" and is intentionally
+ * left build-time baked (Issue #1359).
+ *
+ * @returns Client bundle version string (e.g., "0.2.3"), or "0.0.0" as fallback
+ */
+function getClientVersion() {
+    return process.env.NEXT_PUBLIC_APP_VERSION ?? '0.0.0';
+}
+/**
+ * Get the server's actually-running version, resolved at runtime.
+ * [Issue #1359] Prefers the installed package.json (runtime truth) over the
+ * build-time baked `NEXT_PUBLIC_APP_VERSION`, so update-check reports the version
+ * of the server code that is really running. Separating this from
+ * getClientVersion() is the basis for version-mismatch detection (#1338/#1356).
+ *
+ * Resolution order:
+ *   1. Runtime package.json (name === "commandmate")
+ *   2. Baked NEXT_PUBLIC_APP_VERSION
+ *   3. "0.0.0"
+ *
+ * @returns Server runtime version string (e.g., "0.2.3"), or "0.0.0" as fallback
+ */
+function getServerVersion() {
+    return readRuntimeServerVersion() ?? getClientVersion();
+}
+/**
+ * Get the current application version (server runtime version).
+ * Retained for backward compatibility; delegates to getServerVersion().
+ *
+ * @returns Current version string (e.g., "0.2.3"), or "0.0.0" as fallback
+ */
+function getCurrentVersion() {
+    return getServerVersion();
+}
+/**
+ * Validate that a URL is a legitimate GitHub Releases URL.
+ * [SEC-SF-001] OWASP A03:2021 - Prevents injection via DNS pollution/MITM.
+ *
+ * @param url - URL to validate
+ * @returns Validated URL, or null if invalid
+ */
+function validateReleaseUrl(url) {
+    if (!url.startsWith(github_links_1.GITHUB_RELEASE_URL_PREFIX)) {
+        return null;
+    }
+    return url;
+}
+/**
+ * Sanitize a release name to safe character set.
+ * [SEC-SF-001] Restricts to alphanumeric, dots, hyphens, spaces, underscores, v-prefix.
+ *
+ * @param name - Release name to sanitize
+ * @param tagName - Fallback value (semver-validated tag_name)
+ * @returns Sanitized name, or tagName if the name is invalid
+ */
+function sanitizeReleaseName(name, tagName) {
+    if (RELEASE_NAME_PATTERN.test(name) && name.length <= RELEASE_NAME_MAX_LENGTH) {
+        return name;
+    }
+    // Fallback to tag_name (already validated by SEMVER_PATTERN)
+    return tagName;
+}
+/**
+ * Check GitHub Releases for newer versions.
+ * Uses in-memory cache (globalThis.__versionCheckCache) with 1-hour TTL.
+ * Silently fails on network errors, timeouts, or API issues.
+ *
+ * [SF-002] Multiple calls within the same process are safe: the globalThis cache
+ * (1-hour TTL) ensures that only the first call triggers a network request.
+ * Subsequent calls within the TTL window return the cached result without
+ * network overhead. The cache is stored in globalThis.__versionCheckCache
+ * and automatically invalidated after CACHE_TTL_MS (1 hour).
+ *
+ * @returns Update check result, or null on failure
+ */
+async function checkForUpdate() {
+    try {
+        // Check cache validity
+        if (isCacheValid()) {
+            return cache.result;
+        }
+        // Check rate limit
+        if (isRateLimited()) {
+            return cache.result;
+        }
+        const response = await fetch(exports.GITHUB_API_URL, {
+            headers: {
+                'Accept': 'application/vnd.github+json',
+                'User-Agent': `CommandMate/${getCurrentVersion()}`, // [SEC-SF-002]
+            },
+            cache: 'no-store', // Issue #278: Prevent Next.js Data Cache from caching GitHub API responses
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+        // Handle rate limit (403)
+        if (response.status === 403) {
+            handleRateLimit(response);
+            return cache.result;
+        }
+        if (!response.ok) {
+            return cache.result;
+        }
+        const data = (await response.json());
+        const currentVersion = getCurrentVersion();
+        const latestVersion = data.tag_name.replace(/^v/, '');
+        const hasUpdate = isNewerVersion(currentVersion, data.tag_name);
+        const result = {
+            hasUpdate,
+            currentVersion,
+            latestVersion,
+            releaseUrl: validateReleaseUrl(data.html_url),
+            releaseName: sanitizeReleaseName(data.name, data.tag_name),
+            publishedAt: data.published_at,
+        };
+        // Update cache
+        cache.result = result;
+        cache.fetchedAt = Date.now();
+        return result;
+    }
+    catch {
+        // Silent failure: network errors, timeouts, parse errors
+        return cache.result;
+    }
+}
+/**
+ * Reset cache for testing purposes only.
+ * @internal
+ */
+function resetCacheForTesting() {
+    cache.result = null;
+    cache.fetchedAt = 0;
+    cache.rateLimitResetAt = null;
+}
+// =============================================================================
+// Internal Functions
+// =============================================================================
+/** Check if cache is valid (within TTL) */
+function isCacheValid() {
+    return cache.result !== null && (Date.now() - cache.fetchedAt) < CACHE_TTL_MS;
+}
+/**
+ * Check if currently rate-limited.
+ * [C-001] Simplified rate limit handling: uses rateLimitResetAt from 403 response.
+ */
+function isRateLimited() {
+    if (!cache.rateLimitResetAt)
+        return false;
+    if (Date.now() >= cache.rateLimitResetAt) {
+        cache.rateLimitResetAt = null;
+        return false;
+    }
+    return true;
+}
+/**
+ * Handle 403 rate limit response.
+ * Extracts X-RateLimit-Reset header for precise retry timing,
+ * or falls back to CACHE_TTL_MS extension.
+ */
+function handleRateLimit(response) {
+    const resetTimestamp = response.headers.get('X-RateLimit-Reset');
+    if (resetTimestamp) {
+        cache.rateLimitResetAt = parseInt(resetTimestamp, 10) * 1000;
+    }
+    else {
+        // Reset time unknown: retry after 1 hour
+        cache.rateLimitResetAt = Date.now() + CACHE_TTL_MS;
+    }
+}