quotacap 0.0.25 → 0.0.26

package/dist/cli/update.js

@@ -4,7 +4,7 @@ import { ensureConfig, getDbPath } from "../config.js";
 import { createServiceClient, ServiceError, ServiceUnavailable, } from "../runtime/client.js";
 import { readClaim } from "../runtime/owner.js";
 import { compareVersions } from "../runtime/versions.js";
-import { detectChannel, resolveLatestVersion, updateNpm, updateStandalone, writeUpdateCache, } from "../runtime/updates.js";
+import { detectChannel, resolveLatestVersionDetailed, updateNpm, updateStandalone, writeUpdateCache, } from "../runtime/updates.js";
 import { isServiceManaged, runServiceCommand } from "../service/index.js";
 import { checkSkew, formatWedged, olderCliWarning, takeoverManaged, takeoverUnmanaged, WedgedError, } from "./takeover.js";
 export function stoppedDaemonMessage(oldVersion, newVersion) {
@@ -137,6 +137,17 @@ export async function postUpdateTakeover(opts) {
 function stripV(v) {
     return v.startsWith("v") ? v.slice(1) : v;
 }
+// A rate-limited response names its reset (local HH:MM) and the pin escape
+// hatch; every other failure keeps the generic network message.
+function rateLimitError(resetsAtMs) {
+    const hint = "or run 'quotacap update --to <version>'";
+    if (resetsAtMs === null) {
+        return `GitHub's anonymous API rate limit is exhausted; retry later, ${hint}`;
+    }
+    const d = new Date(resetsAtMs);
+    const hhmm = `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+    return `GitHub's anonymous API rate limit is exhausted (resets ${hhmm}); retry then, ${hint}`;
+}
 export function registerUpdateCommand(program, deps) {
     const exit = deps?.exit ?? process.exit;
     const fetchFn = deps?.fetchFn ?? fetch;
@@ -146,7 +157,7 @@ export function registerUpdateCommand(program, deps) {
         .command("update")
         .description("check for and apply updates")
         .option("--check", "only check for updates, changing nothing")
-        .option("--version <v>", "update to a specific version")
+        .option("--to <version>", "update to a specific version")
         .option("--json", "machine-readable output")
         .action(async (o) => {
         const current = VERSION;
@@ -176,17 +187,24 @@ export function registerUpdateCommand(program, deps) {
             exit(1);
             return;
         }
-        const pin = typeof o.version === "string" && o.version ? stripV(o.version) : null;
+        const pin = typeof o.to === "string" && o.to ? stripV(o.to) : null;
         let latest = null;
+        let rateLimited = null;
         try {
-            latest = await resolveLatestVersion({ fetchFn });
+            const resolved = await resolveLatestVersionDetailed({ fetchFn });
+            if (resolved.status === "ok")
+                latest = resolved.release;
+            else if (resolved.status === "rate-limited")
+                rateLimited = resolved;
         }
         catch {
             latest = null;
         }
         const target = pin ?? latest?.version ?? null;
         if (!target) {
-            const error = "could not resolve the latest release; check your network and retry";
+            const error = rateLimited
+                ? rateLimitError(rateLimited.resetsAtMs)
+                : "could not resolve the latest release; check your network and retry";
             if (asJson) {
                 emit({
                     channel,

package/dist/runtime/updates.d.ts

@@ -13,7 +13,21 @@ export interface ReleaseInfo {
     url: string;
 }
 export declare function releasesApiUrl(): string;
+export declare function releasesPageUrl(): string;
 export declare function releaseDownloadBase(version: string): string;
+export type LatestVersionResolution = {
+    status: "ok";
+    release: ReleaseInfo;
+} | {
+    status: "rate-limited";
+    resetsAtMs: number | null;
+} | {
+    status: "unavailable";
+};
+export declare function resolveLatestVersionDetailed(opts?: {
+    fetchFn?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<LatestVersionResolution>;
 export declare function resolveLatestVersion(opts?: {
     fetchFn?: typeof fetch;
     timeoutMs?: number;
@@ -23,11 +37,13 @@ export interface UpdateCache {
     latest: string;
     channel: string;
     current: string;
+    lastFailureAt?: string;
 }
 export declare function updatesCachePath(): string;
 export declare function readUpdateCache(p?: string): UpdateCache | null;
 export declare function writeUpdateCache(cache: UpdateCache, p?: string): void;
 export declare const UPDATE_CACHE_TTL_MS: number;
+export declare const UPDATE_FAILURE_RETRY_MS: number;
 export declare function updateCacheStale(cache: UpdateCache | null, nowMs?: number): boolean;
 export declare function refreshUpdateCache(opts: {
     channel: string;

package/dist/runtime/updates.js

@@ -129,6 +129,33 @@ export function releasesApiUrl() {
         return `${base}/api/releases/latest`;
     return "https://api.github.com/repos/carlosboeing/quotacap/releases/latest";
 }
+// Default version endpoint: the releases page answers 302 to the latest tag
+// and sits outside the anonymous API rate-limit bucket shared with every
+// other API consumer on the machine.
+export function releasesPageUrl() {
+    return "https://github.com/carlosboeing/quotacap/releases/latest";
+}
+// Header read that tolerates real Headers and the plain-object headers that
+// hermetic fetch mocks use.
+function responseHeader(res, name) {
+    const headers = res.headers;
+    if (!headers)
+        return null;
+    if (typeof headers.get === "function") {
+        return headers.get(name);
+    }
+    if (typeof headers === "object") {
+        for (const [k, v] of Object.entries(headers)) {
+            if (k.toLowerCase() === name && typeof v === "string")
+                return v;
+        }
+    }
+    return null;
+}
+function tagFromReleaseUrl(location) {
+    const m = /\/releases\/tag\/([^/?#]+)/.exec(location);
+    return m ? m[1] : "";
+}
 export function releaseDownloadBase(version) {
     const base = process.env.QUOTACAP_RELEASE_BASE_URL?.replace(/\/+$/, "");
     if (base)
@@ -137,32 +164,66 @@ export function releaseDownloadBase(version) {
         ? "https://github.com/carlosboeing/quotacap/releases/latest/download"
         : `https://github.com/carlosboeing/quotacap/releases/download/v${version}`;
 }
-// Latest published version, or null when the release cannot be resolved
-// (network failure, non-200, bad JSON, unparseable tag). Never throws.
-export async function resolveLatestVersion(opts = {}) {
+function rateLimitOrUnavailable(res) {
+    if (responseHeader(res, "x-ratelimit-remaining") === "0") {
+        const reset = responseHeader(res, "x-ratelimit-reset");
+        const secs = reset !== null && reset.trim() !== "" ? Number(reset) : NaN;
+        return {
+            status: "rate-limited",
+            resetsAtMs: Number.isFinite(secs) ? secs * 1000 : null,
+        };
+    }
+    return { status: "unavailable" };
+}
+// Full resolution outcome: the release, a rate-limited response carrying its
+// reset time, or an undifferentiated failure. Never throws.
+export async function resolveLatestVersionDetailed(opts = {}) {
     const fetchFn = opts.fetchFn ?? fetch;
     const timeoutMs = opts.timeoutMs ?? 10000;
+    const base = process.env.QUOTACAP_RELEASE_BASE_URL?.replace(/\/+$/, "");
     try {
-        const res = await fetchFn(releasesApiUrl(), {
-            headers: { accept: "application/vnd.github+json" },
+        if (base) {
+            const res = await fetchFn(releasesApiUrl(), {
+                headers: { accept: "application/vnd.github+json" },
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            if (res.ok) {
+                const body = (await res.json());
+                const tag = typeof body?.tag_name === "string" ? body.tag_name : "";
+                const version = tag.startsWith("v") ? tag.slice(1) : tag;
+                if (parseVersion(version)) {
+                    const url = typeof body?.html_url === "string" && body.html_url
+                        ? body.html_url
+                        : "https://github.com/carlosboeing/quotacap/releases/latest";
+                    return { status: "ok", release: { version, url } };
+                }
+            }
+            return rateLimitOrUnavailable(res);
+        }
+        const res = await fetchFn(releasesPageUrl(), {
+            redirect: "manual",
             signal: AbortSignal.timeout(timeoutMs),
         });
-        if (!res.ok)
-            return null;
-        const body = (await res.json());
-        const tag = typeof body?.tag_name === "string" ? body.tag_name : "";
-        const version = tag.startsWith("v") ? tag.slice(1) : tag;
-        if (!parseVersion(version))
-            return null;
-        const url = typeof body?.html_url === "string" && body.html_url
-            ? body.html_url
-            : "https://github.com/carlosboeing/quotacap/releases/latest";
-        return { version, url };
+        if (res.status >= 300 && res.status < 400) {
+            const location = responseHeader(res, "location") ?? "";
+            const tag = tagFromReleaseUrl(location);
+            const version = tag.startsWith("v") ? tag.slice(1) : tag;
+            if (tag && parseVersion(version)) {
+                return { status: "ok", release: { version, url: location } };
+            }
+        }
+        return rateLimitOrUnavailable(res);
     }
     catch {
-        return null;
+        return { status: "unavailable" };
     }
 }
+// Latest published version, or null when the release cannot be resolved
+// (network failure, non-redirect, bad JSON, unparseable tag). Never throws.
+export async function resolveLatestVersion(opts = {}) {
+    const r = await resolveLatestVersionDetailed(opts);
+    return r.status === "ok" ? r.release : null;
+}
 export function updatesCachePath() {
     return path.join(process.env.QUOTACAP_HOME ?? os.homedir(), ".quotacap", "updates.json");
 }
@@ -180,6 +241,11 @@ export function readUpdateCache(p = updatesCachePath()) {
         if (typeof parsed.channel !== "string" || typeof parsed.current !== "string") {
             return null;
         }
+        if (parsed.lastFailureAt !== undefined &&
+            (typeof parsed.lastFailureAt !== "string" ||
+                Number.isNaN(new Date(parsed.lastFailureAt).getTime()))) {
+            return null;
+        }
         return parsed;
     }
     catch {
@@ -201,25 +267,48 @@ export function writeUpdateCache(cache, p = updatesCachePath()) {
     catch { }
 }
 export const UPDATE_CACHE_TTL_MS = 24 * 3600 * 1000;
+// Negative-cache floor: a failed refresh suppresses further network attempts
+// for this long. Short against the daily TTL so a recovered endpoint is
+// re-probed soon, long enough that status/advise/poll storms back off.
+export const UPDATE_FAILURE_RETRY_MS = 30 * 60 * 1000;
 export function updateCacheStale(cache, nowMs = Date.now()) {
     if (!cache)
         return true;
     return nowMs - new Date(cache.checkedAt).getTime() >= UPDATE_CACHE_TTL_MS;
 }
-// Refresh the daily cache when older than 24 hours or absent. Network failure
-// keeps the old cache silently; the result is the cache to read from.
+// Refresh the daily cache when older than 24 hours or absent. A failure
+// inside the retry floor performs no network call and keeps serving the
+// previously cached latest; a fresh failure stamps lastFailureAt so the next
+// attempt backs off. checkedAt is never stamped on failure, so the daily
+// check is unaffected. The result is the cache to read from.
 export async function refreshUpdateCache(opts) {
     const cachePath = opts.cachePath ?? updatesCachePath();
     const existing = readUpdateCache(cachePath);
     const now = opts.now?.() ?? new Date();
     if (!updateCacheStale(existing, now.getTime()))
         return existing;
+    if (existing?.lastFailureAt &&
+        now.getTime() - new Date(existing.lastFailureAt).getTime() < UPDATE_FAILURE_RETRY_MS) {
+        return existing;
+    }
     const latest = await resolveLatestVersion({
         fetchFn: opts.fetchFn,
         timeoutMs: opts.timeoutMs ?? 3000,
     });
-    if (!latest)
-        return existing;
+    if (!latest) {
+        if (!existing)
+            return existing;
+        // Re-read before stamping: a concurrent refresh may have succeeded while
+        // our request was in flight, and stamping our stale snapshot would
+        // clobber its newer write and suppress retries for the floor.
+        const current = readUpdateCache(cachePath);
+        if (current && JSON.stringify(current) !== JSON.stringify(existing)) {
+            return current;
+        }
+        const stamped = { ...existing, lastFailureAt: now.toISOString() };
+        writeUpdateCache(stamped, cachePath);
+        return stamped;
+    }
     const fresh = {
         checkedAt: now.toISOString(),
         latest: latest.version,

package/dist/version.js

@@ -1,2 +1,2 @@
 // generated by scripts/build-embed.mjs — do not edit
-export const VERSION = "0.0.25";
+export const VERSION = "0.0.26";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quotacap",
-  "version": "0.0.25",
+  "version": "0.0.26",
   "description": "Local quota tracker for AI coding plans with a dashboard, CLI, MCP server, and next-plan recommendations.",
   "license": "MIT",
   "keywords": [