kanban-ai 0.19.2 → 0.19.3

package/dist/github.js

@@ -1,11 +1,186 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.GithubRateLimitError = void 0;
 exports.getLatestRelease = getLatestRelease;
 exports.getReleaseByVersion = getReleaseByVersion;
+exports.resolveLatestReleaseAssetViaRedirect = resolveLatestReleaseAssetViaRedirect;
+exports.resolveReleaseAssetViaRedirect = resolveReleaseAssetViaRedirect;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
 const version_1 = require("./version");
+class GithubRateLimitError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.name = 'GithubRateLimitError';
+        this.status = options.status;
+        this.retryAfterSeconds = options.retryAfterSeconds;
+        this.rateLimitResetSeconds = options.rateLimitResetSeconds;
+    }
+}
+exports.GithubRateLimitError = GithubRateLimitError;
 const GITHUB_API_BASE = 'https://api.github.com';
-async function githubFetch(path) {
-    const url = `${GITHUB_API_BASE}${path}`;
+const DEFAULT_CACHE_TTL_MS = 30 * 60000;
+function nowMs(cache) {
+    return cache?.now ?? Date.now();
+}
+function resolveTtlMs(cache) {
+    if (cache?.ttlMs === undefined)
+        return DEFAULT_CACHE_TTL_MS;
+    return cache.ttlMs;
+}
+function isFresh(entry, ttlMs, now) {
+    if (entry.fetchedAt > now)
+        return false;
+    return now - entry.fetchedAt < ttlMs;
+}
+function cacheFilePath(cacheDir, repo, apiPath) {
+    const baseDir = node_path_1.default.resolve(cacheDir);
+    const repoKey = repo.replace(/[^a-zA-Z0-9._-]+/g, '__');
+    const repoHash = (0, node_crypto_1.createHash)('sha256').update(repo).digest('hex').slice(0, 12);
+    const repoSafe = repoKey === '' || repoKey === '.' || repoKey === '..' ? `repo-${repoHash}` : repoKey;
+    const key = (0, node_crypto_1.createHash)('sha256')
+        .update(`${GITHUB_API_BASE}${apiPath}`)
+        .digest('hex')
+        .slice(0, 32);
+    const fileName = `${key}.json`;
+    const candidate = node_path_1.default.resolve(baseDir, repoSafe, fileName);
+    if (!candidate.startsWith(`${baseDir}${node_path_1.default.sep}`)) {
+        return node_path_1.default.join(baseDir, `repo-${repoHash}`, fileName);
+    }
+    return candidate;
+}
+async function readCacheEntry(filePath) {
+    try {
+        const raw = await node_fs_1.default.promises.readFile(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        if (typeof parsed.fetchedAt !== 'number')
+            return null;
+        if (!('data' in parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+async function tryUnlink(filePath) {
+    try {
+        await node_fs_1.default.promises.unlink(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function tryRename(from, to) {
+    try {
+        await node_fs_1.default.promises.rename(from, to);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function tryCopyFile(from, to) {
+    try {
+        await node_fs_1.default.promises.copyFile(from, to);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function writeCacheEntry(filePath, entry) {
+    const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    try {
+        await node_fs_1.default.promises.mkdir(node_path_1.default.dirname(filePath), { recursive: true });
+        await node_fs_1.default.promises.writeFile(tmpPath, JSON.stringify(entry), 'utf8');
+        if (await tryRename(tmpPath, filePath))
+            return;
+        if (await tryCopyFile(tmpPath, filePath))
+            return;
+        await tryUnlink(filePath);
+        await tryRename(tmpPath, filePath);
+    }
+    catch {
+        return;
+    }
+    finally {
+        await tryUnlink(tmpPath);
+    }
+}
+function parseRateLimitInfo(res) {
+    const retryAfterRaw = res.headers.get('retry-after');
+    const resetRaw = res.headers.get('x-ratelimit-reset');
+    const remainingRaw = res.headers.get('x-ratelimit-remaining');
+    const retryAfterSeconds = retryAfterRaw ? Number.parseInt(retryAfterRaw, 10) : undefined;
+    const rateLimitResetSeconds = resetRaw ? Number.parseInt(resetRaw, 10) : undefined;
+    const rateLimitRemaining = remainingRaw ? Number.parseInt(remainingRaw, 10) : undefined;
+    return {
+        retryAfterSeconds: Number.isFinite(retryAfterSeconds) ? retryAfterSeconds : undefined,
+        rateLimitResetSeconds: Number.isFinite(rateLimitResetSeconds) ? rateLimitResetSeconds : undefined,
+        rateLimitRemaining: Number.isFinite(rateLimitRemaining) ? rateLimitRemaining : undefined,
+    };
+}
+function formatWaitMs(ms) {
+    const seconds = Math.ceil(ms / 1000);
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.ceil(seconds / 60);
+    return `${minutes}m`;
+}
+function formatRateLimitMessage(info, now) {
+    if (info.retryAfterSeconds && info.retryAfterSeconds > 0) {
+        return `GitHub API rate limited (retry after ${formatWaitMs(info.retryAfterSeconds * 1000)}).`;
+    }
+    if (info.rateLimitRemaining === 0 && info.rateLimitResetSeconds) {
+        const resetAtMs = info.rateLimitResetSeconds * 1000;
+        const waitMs = Math.max(0, resetAtMs - now);
+        const resetIso = new Date(resetAtMs).toISOString();
+        return `GitHub API rate limit exceeded (resets at ${resetIso}, ~${formatWaitMs(waitMs)}).`;
+    }
+    return 'GitHub API is temporarily rate limiting requests.';
+}
+function isRedirectStatus(status) {
+    return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+}
+function assertAllowedRedirectUrl(url) {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'https:') {
+        throw new Error(`Unexpected redirect protocol: ${parsed.protocol}`);
+    }
+    if (parsed.hostname === 'github.com') {
+        return;
+    }
+    if (parsed.hostname.endsWith('.githubusercontent.com')) {
+        return;
+    }
+    throw new Error(`Unexpected redirect host: ${parsed.hostname}`);
+}
+function extractTagFromDownloadUrl(url) {
+    try {
+        const u = new URL(url);
+        const parts = u.pathname.split('/').filter(Boolean);
+        const downloadIdx = parts.indexOf('download');
+        if (downloadIdx <= 0)
+            return null;
+        if (parts[downloadIdx - 1] !== 'releases')
+            return null;
+        const tag = parts[downloadIdx + 1];
+        return tag || null;
+    }
+    catch {
+        return null;
+    }
+}
+async function githubFetchJson(repo, apiPath, options) {
+    const url = `${GITHUB_API_BASE}${apiPath}`;
     const headers = {
         Accept: 'application/vnd.github+json',
         'User-Agent': 'kanban-ai-cli',
@@ -14,24 +189,139 @@ async function githubFetch(path) {
     if (token) {
         headers.Authorization = `Bearer ${token}`;
     }
+    const cache = options?.cache;
+    const ttlMs = resolveTtlMs(cache);
+    const now = nowMs(cache);
+    const filePath = cache ? cacheFilePath(cache.dir, repo, apiPath) : null;
+    const cached = filePath ? await readCacheEntry(filePath) : null;
+    if (cached && isFresh(cached, ttlMs, now)) {
+        return { data: cached.data, meta: { source: 'cache' } };
+    }
+    if (cached?.etag) {
+        headers['If-None-Match'] = cached.etag;
+    }
     const res = await fetch(url, {
         headers,
         redirect: 'follow',
     });
+    if (res.status === 304 && cached) {
+        if (filePath) {
+            const etag = res.headers.get('etag') || cached.etag;
+            await writeCacheEntry(filePath, {
+                etag: etag || undefined,
+                fetchedAt: now,
+                data: cached.data,
+            });
+        }
+        return { data: cached.data, meta: { source: 'cache' } };
+    }
     if (!res.ok) {
+        const info = res.status === 403 || res.status === 429 ? parseRateLimitInfo(res) : null;
         const body = await res.text().catch(() => '');
-        throw new Error(`GitHub API request failed: ${res.status} ${res.statusText}${body ? ` - ${body}` : ''}`);
+        const bodySnippet = body ? body.slice(0, 500) : '';
+        const looksLikeRateLimit = res.status === 429 ||
+            /rate limit/i.test(bodySnippet) ||
+            Boolean(info?.retryAfterSeconds) ||
+            info?.rateLimitRemaining === 0;
+        if (looksLikeRateLimit && info && cached) {
+            return {
+                data: cached.data,
+                meta: {
+                    source: 'stale-cache',
+                    warning: `${formatRateLimitMessage(info, now)} Tip: set GITHUB_TOKEN or GH_TOKEN for higher GitHub rate limits.`,
+                },
+            };
+        }
+        if (looksLikeRateLimit && info) {
+            const message = `${formatRateLimitMessage(info, now)} Tip: set GITHUB_TOKEN or GH_TOKEN for higher GitHub rate limits.`;
+            throw new GithubRateLimitError(message, {
+                status: res.status,
+                retryAfterSeconds: info.retryAfterSeconds,
+                rateLimitResetSeconds: info.rateLimitResetSeconds,
+            });
+        }
+        throw new Error(`GitHub API request failed: ${res.status} ${res.statusText}${bodySnippet ? ` - ${bodySnippet}` : ''}`);
     }
-    return res;
-}
-async function getLatestRelease(repo) {
-    const res = await githubFetch(`/repos/${repo}/releases/latest`);
     const json = (await res.json());
-    const version = (0, version_1.cleanVersionTag)(json.tag_name);
-    return { version, release: json };
+    if (filePath) {
+        const etag = res.headers.get('etag') || undefined;
+        await writeCacheEntry(filePath, { etag, fetchedAt: now, data: json });
+    }
+    return { data: json, meta: { source: 'network' } };
 }
-async function getReleaseByVersion(repo, version) {
+async function getLatestRelease(repo, options) {
+    const result = await githubFetchJson(repo, `/repos/${repo}/releases/latest`, options);
+    const version = (0, version_1.cleanVersionTag)(result.data.tag_name);
+    return { version, release: result.data, meta: result.meta };
+}
+async function getReleaseByVersion(repo, version, options) {
+    const tag = version.startsWith('v') ? version : `v${version}`;
+    const result = await githubFetchJson(repo, `/repos/${repo}/releases/tags/${encodeURIComponent(tag)}`, options);
+    const resolvedVersion = (0, version_1.cleanVersionTag)(result.data.tag_name);
+    return { version: resolvedVersion, release: result.data, meta: result.meta };
+}
+async function resolveLatestReleaseAssetViaRedirect(repo, assetNameCandidates) {
+    for (const assetName of assetNameCandidates) {
+        const latestUrl = `https://github.com/${repo}/releases/latest/download/${assetName}`;
+        const res = await fetch(latestUrl, { redirect: 'manual', method: 'HEAD' });
+        if (!isRedirectStatus(res.status)) {
+            continue;
+        }
+        const firstLocation = res.headers.get('location');
+        if (!firstLocation) {
+            continue;
+        }
+        const releaseUrl = new URL(firstLocation, latestUrl).toString();
+        assertAllowedRedirectUrl(releaseUrl);
+        const tag = extractTagFromDownloadUrl(releaseUrl);
+        if (!tag) {
+            continue;
+        }
+        const res2 = await fetch(releaseUrl, { redirect: 'manual', method: 'HEAD' });
+        if (!isRedirectStatus(res2.status)) {
+            if (res2.status >= 200 && res2.status < 300) {
+                return { tag, version: (0, version_1.cleanVersionTag)(tag), assetName, url: releaseUrl };
+            }
+            continue;
+        }
+        const secondLocation = res2.headers.get('location');
+        if (!secondLocation) {
+            continue;
+        }
+        const assetUrl = new URL(secondLocation, releaseUrl).toString();
+        assertAllowedRedirectUrl(assetUrl);
+        return { tag, version: (0, version_1.cleanVersionTag)(tag), assetName, url: assetUrl };
+    }
+    throw new Error(`Could not resolve latest release download URL for ${repo} (tried: ${assetNameCandidates.join(', ')})`);
+}
+async function resolveReleaseAssetViaRedirect(repo, version, assetNameCandidates) {
     const tag = version.startsWith('v') ? version : `v${version}`;
-    const res = await githubFetch(`/repos/${repo}/releases/tags/${encodeURIComponent(tag)}`);
-    return (await res.json());
+    for (const assetName of assetNameCandidates) {
+        const releaseUrl = `https://github.com/${repo}/releases/download/${tag}/${assetName}`;
+        const res = await fetch(releaseUrl, { redirect: 'manual', method: 'HEAD' });
+        if (!isRedirectStatus(res.status)) {
+            if (res.status >= 200 && res.status < 300) {
+                return {
+                    tag,
+                    version: (0, version_1.cleanVersionTag)(tag),
+                    assetName,
+                    url: releaseUrl,
+                };
+            }
+            continue;
+        }
+        const location = res.headers.get('location');
+        if (!location) {
+            continue;
+        }
+        const assetUrl = new URL(location, releaseUrl).toString();
+        assertAllowedRedirectUrl(assetUrl);
+        return {
+            tag,
+            version: (0, version_1.cleanVersionTag)(tag),
+            assetName,
+            url: assetUrl,
+        };
+    }
+    throw new Error(`Could not resolve release download URL for ${repo}@${tag} (tried: ${assetNameCandidates.join(', ')})`);
 }

package/dist/github.test.js

@@ -1,5 +1,11 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
 const vitest_1 = require("vitest");
 const github_1 = require("./github");
 const originalFetch = globalThis.fetch;
@@ -41,7 +47,8 @@ const originalEnv = { ...process.env };
             text: async () => "",
         });
         globalThis.fetch = fetchMock;
-        const release = await (0, github_1.getReleaseByVersion)("owner/repo", "2.0.0");
+        const { version, release } = await (0, github_1.getReleaseByVersion)("owner/repo", "2.0.0");
+        (0, vitest_1.expect)(version).toBe("2.0.0");
         (0, vitest_1.expect)(release.tag_name).toBe("v2.0.0");
         (0, vitest_1.expect)(fetchMock).toHaveBeenCalledWith("https://api.github.com/repos/owner/repo/releases/tags/v2.0.0", vitest_1.expect.any(Object));
     });
@@ -73,4 +80,445 @@ const originalEnv = { ...process.env };
         globalThis.fetch = fetchMock;
         await (0, vitest_1.expect)((0, github_1.getLatestRelease)("owner/repo")).rejects.toThrow(/GitHub API request failed: 404 Not Found/);
     });
+    (0, vitest_1.it)("caches latest release responses on disk with TTL", async () => {
+        const tmpDir = await node_fs_1.default.promises.mkdtemp(node_path_1.default.join(node_os_1.default.tmpdir(), "kanban-ai-cli-github-"));
+        try {
+            const fetchMock = vitest_1.vi.fn().mockResolvedValue({
+                ok: true,
+                status: 200,
+                statusText: "OK",
+                headers: {
+                    get: (name) => name.toLowerCase() === "etag" ? "\"etag\"" : null,
+                },
+                json: async () => ({
+                    tag_name: "v1.2.3",
+                    assets: [],
+                }),
+                text: async () => "",
+            });
+            globalThis.fetch = fetchMock;
+            const first = await (0, github_1.getLatestRelease)("owner/repo", {
+                cache: { dir: tmpDir, ttlMs: 60000, now: 1000 },
+            });
+            const second = await (0, github_1.getLatestRelease)("owner/repo", {
+                cache: { dir: tmpDir, ttlMs: 60000, now: 2000 },
+            });
+            (0, vitest_1.expect)(first.version).toBe("1.2.3");
+            (0, vitest_1.expect)(second.version).toBe("1.2.3");
+            (0, vitest_1.expect)(fetchMock).toHaveBeenCalledTimes(1);
+        }
+        finally {
+            await node_fs_1.default.promises.rm(tmpDir, { recursive: true, force: true });
+        }
+    });
+    (0, vitest_1.it)("uses If-None-Match and reuses cached body on 304", async () => {
+        const tmpDir = await node_fs_1.default.promises.mkdtemp(node_path_1.default.join(node_os_1.default.tmpdir(), "kanban-ai-cli-github-"));
+        try {
+            const fetchMock = vitest_1.vi
+                .fn()
+                .mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                statusText: "OK",
+                headers: {
+                    get: (name) => name.toLowerCase() === "etag" ? "\"etag\"" : null,
+                },
+                json: async () => ({
+                    tag_name: "v1.2.3",
+                    assets: [],
+                }),
+                text: async () => "",
+            })
+                .mockResolvedValueOnce({
+                ok: false,
+                status: 304,
+                statusText: "Not Modified",
+                headers: {
+                    get: (name) => name.toLowerCase() === "etag" ? "\"etag\"" : null,
+                },
+                json: async () => ({}),
+                text: async () => "",
+            });
+            globalThis.fetch = fetchMock;
+            await (0, github_1.getLatestRelease)("owner/repo", {
+                cache: { dir: tmpDir, ttlMs: 1, now: 0 },
+            });
+            const second = await (0, github_1.getLatestRelease)("owner/repo", {
+                cache: { dir: tmpDir, ttlMs: 1, now: 10 },
+            });
+            (0, vitest_1.expect)(second.version).toBe("1.2.3");
+            (0, vitest_1.expect)(fetchMock).toHaveBeenCalledTimes(2);
+            const [, options] = fetchMock.mock.calls[1];
+            (0, vitest_1.expect)(options.headers["If-None-Match"]).toBe("\"etag\"");
+        }
+        finally {
+            await node_fs_1.default.promises.rm(tmpDir, { recursive: true, force: true });
+        }
+    });
+    (0, vitest_1.it)("respects ttlMs=0 for immediate revalidation", async () => {
+        const tmpDir = await node_fs_1.default.promises.mkdtemp(node_path_1.default.join(node_os_1.default.tmpdir(), "kanban-ai-cli-github-"));
+        try {
+            const fetchMock = vitest_1.vi
+                .fn()
+                .mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                statusText: "OK",
+                headers: {
+                    get: (name) => name.toLowerCase() === "etag" ? "\"etag\"" : null,
+                },
+                json: async () => ({
+                    tag_name: "v1.2.3",
+                    assets: [],
+                }),
+                text: async () => "",
+            })
+                .mockResolvedValueOnce({
+                ok: false,
+                status: 304,
+                statusText: "Not Modified",
+                headers: {
+                    get: (name) => name.toLowerCase() === "etag" ? "\"etag\"" : null,
+                },
+                json: async () => ({}),
+                text: async () => "",
+            });
+            globalThis.fetch = fetchMock;
+            await (0, github_1.getLatestRelease)("owner/repo", {
+                cache: { dir: tmpDir, ttlMs: 0, now: 0 },
+            });
+            await (0, github_1.getLatestRelease)("owner/repo", {
+                cache: { dir: tmpDir, ttlMs: 0, now: 1 },
+            });
+            (0, vitest_1.expect)(fetchMock).toHaveBeenCalledTimes(2);
+            const [, options] = fetchMock.mock.calls[1];
+            (0, vitest_1.expect)(options.headers["If-None-Match"]).toBe("\"etag\"");
+        }
+        finally {
+            await node_fs_1.default.promises.rm(tmpDir, { recursive: true, force: true });
+        }
+    });
+    (0, vitest_1.it)("writes cache entries even when rename fails", async () => {
+        const tmpDir = await node_fs_1.default.promises.mkdtemp(node_path_1.default.join(node_os_1.default.tmpdir(), "kanban-ai-cli-github-"));
+        const renameSpy = vitest_1.vi
+            .spyOn(node_fs_1.default.promises, "rename")
+            .mockRejectedValue(new Error("rename failed"));
+        try {
+            const fetchMock = vitest_1.vi.fn().mockResolvedValue({
+                ok: true,
+                status: 200,
+                statusText: "OK",
+                headers: {
+                    get: (name) => name.toLowerCase() === "etag" ? "\"etag\"" : null,
+                },
+                json: async () => ({
+                    tag_name: "v1.2.3",
+                    assets: [],
+                }),
+                text: async () => "",
+            });
+            globalThis.fetch = fetchMock;
+            await (0, github_1.getLatestRelease)("owner/repo", {
+                cache: { dir: tmpDir, ttlMs: 60000, now: 1000 },
+            });
+            await (0, github_1.getLatestRelease)("owner/repo", {
+                cache: { dir: tmpDir, ttlMs: 60000, now: 2000 },
+            });
+            (0, vitest_1.expect)(fetchMock).toHaveBeenCalledTimes(1);
+        }
+        finally {
+            renameSpy.mockRestore();
+            await node_fs_1.default.promises.rm(tmpDir, { recursive: true, force: true });
+        }
+    });
+    (0, vitest_1.it)("keeps cache writes within cache dir for invalid repo names", async () => {
+        const tmpDir = await node_fs_1.default.promises.mkdtemp(node_path_1.default.join(node_os_1.default.tmpdir(), "kanban-ai-cli-github-"));
+        const writeSpy = vitest_1.vi.spyOn(node_fs_1.default.promises, "writeFile");
+        try {
+            const fetchMock = vitest_1.vi.fn().mockResolvedValue({
+                ok: true,
+                status: 200,
+                statusText: "OK",
+                headers: {
+                    get: (name) => name.toLowerCase() === "etag" ? "\"etag\"" : null,
+                },
+                json: async () => ({
+                    tag_name: "v1.2.3",
+                    assets: [],
+                }),
+                text: async () => "",
+            });
+            globalThis.fetch = fetchMock;
+            await (0, github_1.getLatestRelease)("..", {
+                cache: { dir: tmpDir, ttlMs: 60000, now: 0 },
+            });
+            (0, vitest_1.expect)(writeSpy).toHaveBeenCalled();
+            const cacheWritePath = String(writeSpy.mock.calls[0]?.[0]);
+            const resolvedTmpDir = node_path_1.default.resolve(tmpDir);
+            (0, vitest_1.expect)(node_path_1.default.resolve(cacheWritePath).startsWith(`${resolvedTmpDir}${node_path_1.default.sep}`)).toBe(true);
+        }
+        finally {
+            writeSpy.mockRestore();
+            await node_fs_1.default.promises.rm(tmpDir, { recursive: true, force: true });
+        }
+    });
+    (0, vitest_1.it)("treats future cache timestamps as stale", async () => {
+        const tmpDir = await node_fs_1.default.promises.mkdtemp(node_path_1.default.join(node_os_1.default.tmpdir(), "kanban-ai-cli-github-"));
+        try {
+            const fetchMock = vitest_1.vi.fn().mockResolvedValue({
+                ok: true,
+                status: 200,
+                statusText: "OK",
+                headers: {
+                    get: (name) => name.toLowerCase() === "etag" ? "\"etag\"" : null,
+                },
+                json: async () => ({
+                    tag_name: "v1.2.3",
+                    assets: [],
+                }),
+                text: async () => "",
+            });
+            globalThis.fetch = fetchMock;
+            await (0, github_1.getLatestRelease)("owner/repo", {
+                cache: { dir: tmpDir, ttlMs: 60000, now: 1000 },
+            });
+            await (0, github_1.getLatestRelease)("owner/repo", {
+                cache: { dir: tmpDir, ttlMs: 60000, now: 0 },
+            });
+            (0, vitest_1.expect)(fetchMock).toHaveBeenCalledTimes(2);
+        }
+        finally {
+            await node_fs_1.default.promises.rm(tmpDir, { recursive: true, force: true });
+        }
+    });
+    (0, vitest_1.it)("returns cached data with a warning when rate-limited", async () => {
+        const tmpDir = await node_fs_1.default.promises.mkdtemp(node_path_1.default.join(node_os_1.default.tmpdir(), "kanban-ai-cli-github-"));
+        try {
+            const fetchMock = vitest_1.vi
+                .fn()
+                .mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                statusText: "OK",
+                headers: {
+                    get: (name) => name.toLowerCase() === "etag" ? "\"etag\"" : null,
+                },
+                json: async () => ({
+                    tag_name: "v1.2.3",
+                    assets: [],
+                }),
+                text: async () => "",
+            })
+                .mockResolvedValueOnce({
+                ok: false,
+                status: 403,
+                statusText: "Forbidden",
+                headers: {
+                    get: (name) => {
+                        const key = name.toLowerCase();
+                        if (key === "x-ratelimit-remaining")
+                            return "0";
+                        if (key === "x-ratelimit-reset")
+                            return "9999999999";
+                        return null;
+                    },
+                },
+                json: async () => ({}),
+                text: async () => "API rate limit exceeded",
+            });
+            globalThis.fetch = fetchMock;
+            await (0, github_1.getLatestRelease)("owner/repo", {
+                cache: { dir: tmpDir, ttlMs: 1, now: 0 },
+            });
+            const second = await (0, github_1.getLatestRelease)("owner/repo", {
+                cache: { dir: tmpDir, ttlMs: 1, now: 10 },
+            });
+            (0, vitest_1.expect)(second.version).toBe("1.2.3");
+            (0, vitest_1.expect)(second.meta?.source).toBe("stale-cache");
+            (0, vitest_1.expect)(second.meta?.warning).toMatch(/GITHUB_TOKEN|GH_TOKEN/);
+        }
+        finally {
+            await node_fs_1.default.promises.rm(tmpDir, { recursive: true, force: true });
+        }
+    });
+    (0, vitest_1.it)("throws GithubRateLimitError when rate-limited without cache", async () => {
+        const fetchMock = vitest_1.vi.fn().mockResolvedValue({
+            ok: false,
+            status: 403,
+            statusText: "Forbidden",
+            headers: {
+                get: (name) => {
+                    const key = name.toLowerCase();
+                    if (key === "x-ratelimit-remaining")
+                        return "0";
+                    if (key === "x-ratelimit-reset")
+                        return "9999999999";
+                    return null;
+                },
+            },
+            json: async () => ({}),
+            text: async () => "API rate limit exceeded",
+        });
+        globalThis.fetch = fetchMock;
+        await (0, vitest_1.expect)((0, github_1.getLatestRelease)("owner/repo")).rejects.toBeInstanceOf(github_1.GithubRateLimitError);
+    });
+    (0, vitest_1.it)("resolves latest release asset URL via redirect", async () => {
+        const fetchMock = vitest_1.vi
+            .fn()
+            .mockResolvedValueOnce({
+            status: 404,
+            headers: { get: () => null },
+        })
+            .mockResolvedValueOnce({
+            status: 302,
+            headers: {
+                get: (name) => name.toLowerCase() === "location"
+                    ? "https://github.com/owner/repo/releases/download/v9.9.9/asset"
+                    : null,
+            },
+        })
+            .mockResolvedValueOnce({
+            status: 302,
+            headers: {
+                get: (name) => name.toLowerCase() === "location"
+                    ? "https://objects.githubusercontent.com/github-production-release-asset-2e65be/asset"
+                    : null,
+            },
+        });
+        globalThis.fetch = fetchMock;
+        const resolved = await (0, github_1.resolveLatestReleaseAssetViaRedirect)("owner/repo", ["missing", "asset"]);
+        (0, vitest_1.expect)(resolved.tag).toBe("v9.9.9");
+        (0, vitest_1.expect)(resolved.version).toBe("9.9.9");
+        (0, vitest_1.expect)(resolved.assetName).toBe("asset");
+        (0, vitest_1.expect)(resolved.url).toBe("https://objects.githubusercontent.com/github-production-release-asset-2e65be/asset");
+    });
+    (0, vitest_1.it)("does not return a failing release URL in latest redirect flow", async () => {
+        const fetchMock = vitest_1.vi
+            .fn()
+            .mockResolvedValueOnce({
+            status: 302,
+            headers: {
+                get: (name) => name.toLowerCase() === "location"
+                    ? "https://github.com/owner/repo/releases/download/v9.9.9/asset"
+                    : null,
+            },
+        })
+            .mockResolvedValueOnce({
+            status: 404,
+            headers: { get: () => null },
+        });
+        globalThis.fetch = fetchMock;
+        await (0, vitest_1.expect)((0, github_1.resolveLatestReleaseAssetViaRedirect)("owner/repo", ["asset"])).rejects.toThrow(/Could not resolve latest release download URL/);
+    });
+    (0, vitest_1.it)("returns the GitHub release download URL when no redirect occurs", async () => {
+        const fetchMock = vitest_1.vi
+            .fn()
+            .mockResolvedValueOnce({
+            status: 302,
+            headers: {
+                get: (name) => name.toLowerCase() === "location"
+                    ? "https://github.com/owner/repo/releases/download/v9.9.9/asset"
+                    : null,
+            },
+        })
+            .mockResolvedValueOnce({
+            status: 200,
+            headers: { get: () => null },
+        });
+        globalThis.fetch = fetchMock;
+        const resolved = await (0, github_1.resolveLatestReleaseAssetViaRedirect)("owner/repo", [
+            "asset",
+        ]);
+        (0, vitest_1.expect)(resolved.url).toBe("https://github.com/owner/repo/releases/download/v9.9.9/asset");
+    });
+    (0, vitest_1.it)("fails closed when latest redirect is missing a location", async () => {
+        const fetchMock = vitest_1.vi
+            .fn()
+            .mockResolvedValueOnce({
+            status: 302,
+            headers: {
+                get: (name) => name.toLowerCase() === "location"
+                    ? "/owner/repo/releases/download/v9.9.9/asset"
+                    : null,
+            },
+        })
+            .mockResolvedValueOnce({
+            status: 302,
+            headers: { get: () => null },
+        });
+        globalThis.fetch = fetchMock;
+        await (0, vitest_1.expect)((0, github_1.resolveLatestReleaseAssetViaRedirect)("owner/repo", ["asset"])).rejects.toThrow(/Could not resolve latest release download URL/);
+    });
+    (0, vitest_1.it)("resolves a tagged release asset URL via redirect", async () => {
+        const fetchMock = vitest_1.vi
+            .fn()
+            .mockResolvedValueOnce({
+            status: 404,
+            headers: { get: () => null },
+        })
+            .mockResolvedValueOnce({
+            status: 302,
+            headers: {
+                get: (name) => name.toLowerCase() === "location"
+                    ? "https://objects.githubusercontent.com/github-production-release-asset-2e65be/asset"
+                    : null,
+            },
+        });
+        globalThis.fetch = fetchMock;
+        const resolved = await (0, github_1.resolveReleaseAssetViaRedirect)("owner/repo", "1.2.3", [
+            "missing",
+            "asset",
+        ]);
+        (0, vitest_1.expect)(resolved.tag).toBe("v1.2.3");
+        (0, vitest_1.expect)(resolved.version).toBe("1.2.3");
+        (0, vitest_1.expect)(resolved.assetName).toBe("asset");
+        (0, vitest_1.expect)(resolved.url).toBe("https://objects.githubusercontent.com/github-production-release-asset-2e65be/asset");
+    });
+    (0, vitest_1.it)("returns the GitHub download URL when no redirect occurs", async () => {
+        const fetchMock = vitest_1.vi.fn().mockResolvedValueOnce({
+            status: 200,
+            headers: { get: () => null },
+        });
+        globalThis.fetch = fetchMock;
+        const resolved = await (0, github_1.resolveReleaseAssetViaRedirect)("owner/repo", "1.2.3", ["asset"]);
+        (0, vitest_1.expect)(resolved.url).toBe("https://github.com/owner/repo/releases/download/v1.2.3/asset");
+    });
+    (0, vitest_1.it)("skips redirects without a location header", async () => {
+        const fetchMock = vitest_1.vi
+            .fn()
+            .mockResolvedValueOnce({
+            status: 302,
+            headers: { get: () => null },
+        })
+            .mockResolvedValueOnce({
+            status: 302,
+            headers: {
+                get: (name) => name.toLowerCase() === "location"
+                    ? "https://objects.githubusercontent.com/github-production-release-asset-2e65be/asset"
+                    : null,
+            },
+        });
+        globalThis.fetch = fetchMock;
+        const resolved = await (0, github_1.resolveReleaseAssetViaRedirect)("owner/repo", "1.2.3", ["missing", "asset"]);
+        (0, vitest_1.expect)(resolved.assetName).toBe("asset");
+        (0, vitest_1.expect)(resolved.url).toBe("https://objects.githubusercontent.com/github-production-release-asset-2e65be/asset");
+    });
+    (0, vitest_1.it)("rejects unexpected redirect protocols", async () => {
+        const fetchMock = vitest_1.vi.fn().mockResolvedValueOnce({
+            status: 302,
+            headers: {
+                get: (name) => name.toLowerCase() === "location" ? "http://evil.test/asset" : null,
+            },
+        });
+        globalThis.fetch = fetchMock;
+        await (0, vitest_1.expect)((0, github_1.resolveReleaseAssetViaRedirect)("owner/repo", "1.2.3", ["asset"])).rejects.toThrow(/Unexpected redirect protocol/);
+    });
+    (0, vitest_1.it)("throws when tagged release asset cannot be resolved", async () => {
+        const fetchMock = vitest_1.vi.fn().mockResolvedValue({
+            status: 404,
+            headers: { get: () => null },
+        });
+        globalThis.fetch = fetchMock;
+        await (0, vitest_1.expect)((0, github_1.resolveReleaseAssetViaRedirect)("owner/repo", "1.2.3", ["asset"])).rejects.toThrow(/Could not resolve release download URL/);
+    });
 });

package/dist/index.js

@@ -18,6 +18,7 @@ const updates_1 = require("./updates");
 const download_1 = require("./download");
 const cache_1 = require("./cache");
 const help_1 = require("./help");
+const version_1 = require("./version");
 async function runCli() {
     const env = (0, env_1.resolveEnvOptions)();
     const argv = process.argv.slice(2);
@@ -38,7 +39,12 @@ async function runCli() {
     }
     const platformArch = (0, platform_1.detectPlatformArch)();
     const binaryInfo = (0, platform_1.resolveBinaryInfo)(platformArch.platform, platformArch.arch);
-    const explicitVersion = cliOptions.binaryVersion;
+    const githubApiCache = {
+        dir: node_path_1.default.join(node_path_1.default.dirname(effectiveEnv.baseCacheDir), "github-api"),
+    };
+    const explicitVersion = cliOptions.binaryVersion
+        ? (0, version_1.cleanVersionTag)(cliOptions.binaryVersion)
+        : undefined;
     let targetVersion;
     let binaryPath;
     let release;
@@ -51,7 +57,33 @@ async function runCli() {
         }
         else {
             targetVersion = explicitVersion;
-            release = await (0, github_1.getReleaseByVersion)(effectiveEnv.githubRepo, explicitVersion);
+            try {
+                const resolved = await (0, github_1.getReleaseByVersion)(effectiveEnv.githubRepo, explicitVersion, { cache: githubApiCache });
+                if (resolved.meta?.warning) {
+                    process.stderr.write(`${resolved.meta.warning}\n`);
+                }
+                targetVersion = resolved.version;
+                release = resolved.release;
+            }
+            catch (err) {
+                if (err instanceof github_1.GithubRateLimitError) {
+                    // eslint-disable-next-line no-console
+                    console.error(err.message);
+                    const fallback = await (0, github_1.resolveReleaseAssetViaRedirect)(effectiveEnv.githubRepo, explicitVersion, binaryInfo.assetNameCandidates);
+                    release = {
+                        tag_name: fallback.tag,
+                        assets: [
+                            {
+                                name: fallback.assetName,
+                                browser_download_url: fallback.url,
+                            },
+                        ],
+                    };
+                }
+                else {
+                    throw err;
+                }
+            }
         }
     }
     else if (effectiveEnv.noUpdateCheck || effectiveEnv.assumeNo) {
@@ -62,16 +94,45 @@ async function runCli() {
             binaryPath = (0, cache_1.getBinaryPath)(effectiveEnv.baseCacheDir, targetVersion, platformArch, binaryInfo);
         }
         else {
-            // No cached versions yet: fall back to a one-time fetch of the latest release.
-            const { version: latestRemoteVersion, release: latestRelease } = await (0, github_1.getLatestRelease)(effectiveEnv.githubRepo);
-            targetVersion = latestRemoteVersion;
-            release = latestRelease;
+            try {
+                const latest = await (0, github_1.getLatestRelease)(effectiveEnv.githubRepo, { cache: githubApiCache });
+                if (latest.meta?.warning) {
+                    // eslint-disable-next-line no-console
+                    console.error(latest.meta.warning);
+                }
+                targetVersion = latest.version;
+                release = latest.release;
+            }
+            catch (err) {
+                if (err instanceof github_1.GithubRateLimitError) {
+                    // eslint-disable-next-line no-console
+                    console.error(err.message);
+                    const fallback = await (0, github_1.resolveLatestReleaseAssetViaRedirect)(effectiveEnv.githubRepo, binaryInfo.assetNameCandidates);
+                    targetVersion = fallback.version;
+                    release = {
+                        tag_name: fallback.tag,
+                        assets: [
+                            {
+                                name: fallback.assetName,
+                                browser_download_url: fallback.url,
+                            },
+                        ],
+                    };
+                }
+                else {
+                    throw err;
+                }
+            }
         }
     }
     else {
         // Default behavior: consult GitHub to pick the appropriate version, then use cache or download.
         try {
-            const { version: latestRemoteVersion, release: latestRelease } = await (0, github_1.getLatestRelease)(effectiveEnv.githubRepo);
+            const { version: latestRemoteVersion, release: latestRelease, meta } = await (0, github_1.getLatestRelease)(effectiveEnv.githubRepo, { cache: githubApiCache });
+            if (meta?.warning) {
+                // eslint-disable-next-line no-console
+                console.error(meta.warning);
+            }
             const decision = await (0, updates_1.decideVersionToUse)({
                 env: effectiveEnv,
                 platformArch,
@@ -98,7 +159,33 @@ async function runCli() {
                 release = latestRelease;
             }
             else {
-                release = await (0, github_1.getReleaseByVersion)(effectiveEnv.githubRepo, targetVersion);
+                try {
+                    const resolved = await (0, github_1.getReleaseByVersion)(effectiveEnv.githubRepo, targetVersion, { cache: githubApiCache });
+                    if (resolved.meta?.warning) {
+                        process.stderr.write(`${resolved.meta.warning}\n`);
+                    }
+                    targetVersion = resolved.version;
+                    release = resolved.release;
+                }
+                catch (err) {
+                    if (err instanceof github_1.GithubRateLimitError) {
+                        // eslint-disable-next-line no-console
+                        console.error(err.message);
+                        const fallback = await (0, github_1.resolveReleaseAssetViaRedirect)(effectiveEnv.githubRepo, targetVersion, binaryInfo.assetNameCandidates);
+                        release = {
+                            tag_name: fallback.tag,
+                            assets: [
+                                {
+                                    name: fallback.assetName,
+                                    browser_download_url: fallback.url,
+                                },
+                            ],
+                        };
+                    }
+                    else {
+                        throw err;
+                    }
+                }
             }
         }
         catch (err) {
@@ -109,6 +196,21 @@ async function runCli() {
                 // eslint-disable-next-line no-console
                 console.error(`Could not check for updates on GitHub (${err.message}). Using cached KanbanAI ${targetVersion}.`);
             }
+            else if (err instanceof github_1.GithubRateLimitError) {
+                // eslint-disable-next-line no-console
+                console.error(err.message);
+                const fallback = await (0, github_1.resolveLatestReleaseAssetViaRedirect)(effectiveEnv.githubRepo, binaryInfo.assetNameCandidates);
+                targetVersion = fallback.version;
+                release = {
+                    tag_name: fallback.tag,
+                    assets: [
+                        {
+                            name: fallback.assetName,
+                            browser_download_url: fallback.url,
+                        },
+                    ],
+                };
+            }
             else {
                 throw err;
             }

package/dist/index.test.js

@@ -69,31 +69,65 @@ const defaultCliOptions = {
 vitest_1.vi.mock("./args", () => ({
     parseCliArgs: vitest_1.vi.fn(() => ({ ...defaultCliOptions })),
 }));
-vitest_1.vi.mock("./github", () => ({
-    getLatestRelease: () => Promise.resolve({
-        version: "1.0.0",
-        release: {
-            tag_name: "v1.0.0",
-            body: "Test changelog body",
-            assets: [
-                {
-                    name: "kanban-ai-linux-x64",
-                    browser_download_url: "https://example.com/bin",
-                },
-            ],
-        },
-    }),
-    getReleaseByVersion: () => Promise.resolve({
-        tag_name: "v1.0.0",
-        body: "Test changelog body",
-        assets: [
-            {
-                name: "kanban-ai-linux-x64",
-                browser_download_url: "https://example.com/bin",
+vitest_1.vi.mock("./github", () => {
+    class GithubRateLimitError extends Error {
+        constructor(message, options) {
+            super(message);
+            this.name = "GithubRateLimitError";
+            this.status = options?.status ?? 403;
+            this.retryAfterSeconds = options?.retryAfterSeconds;
+            this.rateLimitResetSeconds = options?.rateLimitResetSeconds;
+        }
+    }
+    return {
+        GithubRateLimitError,
+        getLatestRelease: () => Promise.resolve({
+            version: "1.0.0",
+            release: {
+                tag_name: "v1.0.0",
+                body: "Test changelog body",
+                assets: [
+                    {
+                        name: "kanban-ai-linux-x64",
+                        browser_download_url: "https://example.com/bin",
+                    },
+                ],
             },
-        ],
-    }),
-}));
+        }),
+        getReleaseByVersion: () => Promise.resolve({
+            version: "1.0.0",
+            release: {
+                tag_name: "v1.0.0",
+                body: "Test changelog body",
+                assets: [
+                    {
+                        name: "kanban-ai-linux-x64",
+                        browser_download_url: "https://example.com/bin",
+                    },
+                ],
+            },
+        }),
+        resolveLatestReleaseAssetViaRedirect: (repo, assetNameCandidates) => {
+            const assetName = assetNameCandidates[0] ?? "kanban-ai-linux-x64";
+            return Promise.resolve({
+                tag: "v1.0.0",
+                version: "1.0.0",
+                assetName,
+                url: `https://github.com/${repo}/releases/download/v1.0.0/${assetName}`,
+            });
+        },
+        resolveReleaseAssetViaRedirect: (repo, version, assetNameCandidates) => {
+            const tag = version.startsWith("v") ? version : `v${version}`;
+            const assetName = assetNameCandidates[0] ?? "kanban-ai-linux-x64";
+            return Promise.resolve({
+                tag,
+                version: tag.replace(/^v/, ""),
+                assetName,
+                url: `https://github.com/${repo}/releases/download/${tag}/${assetName}`,
+            });
+        },
+    };
+});
 vitest_1.vi.mock("./updates", () => ({
     decideVersionToUse: vitest_1.vi.fn(async (opts) => {
         if (opts && typeof opts.onNewVersionAvailable === "function") {
@@ -212,6 +246,50 @@ vitest_1.vi.mock("node:child_process", () => {
             logSpy.mockRestore();
         }
     });
+    (0, vitest_1.it)("prints a fallback message when no changelog is available", async () => {
+        const exitSpy = vitest_1.vi.fn();
+        const originalExit = process.exit;
+        const githubModule = await Promise.resolve().then(() => __importStar(require("./github")));
+        const getLatestReleaseSpy = vitest_1.vi
+            .spyOn(githubModule, "getLatestRelease")
+            .mockResolvedValueOnce({
+            version: "1.0.0",
+            release: {
+                tag_name: "v1.0.0",
+                body: "",
+                assets: [
+                    {
+                        name: "kanban-ai-linux-x64",
+                        browser_download_url: "https://example.com/bin",
+                    },
+                ],
+            },
+        });
+        const updatesModule = await Promise.resolve().then(() => __importStar(require("./updates")));
+        const decideMock = updatesModule.decideVersionToUse;
+        decideMock.mockImplementationOnce(async (opts) => {
+            if (opts && typeof opts.onNewVersionAvailable === "function") {
+                await opts.onNewVersionAvailable({
+                    latestRemoteVersion: opts.latestRemoteVersion ?? "1.0.0",
+                    latestCachedVersion: undefined,
+                });
+            }
+            return { versionToUse: "1.0.0", fromCache: false };
+        });
+        const logSpy = vitest_1.vi.spyOn(console, "log").mockImplementation(() => { });
+        // @ts-expect-error override for tests
+        process.exit = exitSpy;
+        try {
+            await (0, index_1.runCli)();
+            (0, vitest_1.expect)(logSpy.mock.calls.some((call) => String(call[0]).includes("No changelog was provided for this release."))).toBe(true);
+        }
+        finally {
+            // @ts-expect-error restore original
+            process.exit = originalExit;
+            logSpy.mockRestore();
+            getLatestReleaseSpy.mockRestore();
+        }
+    });
     (0, vitest_1.it)("uses cached version path when decideVersionToUse returns fromCache=true", async () => {
         const exitSpy = vitest_1.vi.fn();
         const originalExit = process.exit;
@@ -241,12 +319,43 @@ vitest_1.vi.mock("node:child_process", () => {
         process.exit = exitSpy;
         try {
             await (0, index_1.runCli)();
-            (0, vitest_1.expect)(getReleaseByVersionSpy).toHaveBeenCalledWith("owner/repo", "0.9.0");
+            (0, vitest_1.expect)(getReleaseByVersionSpy).toHaveBeenCalledWith("owner/repo", "0.9.0", vitest_1.expect.objectContaining({
+                cache: vitest_1.expect.any(Object),
+            }));
+        }
+        finally {
+            // @ts-expect-error restore original
+            process.exit = originalExit;
+            getReleaseByVersionSpy.mockRestore();
+        }
+    });
+    (0, vitest_1.it)("throws when release lookup fails and no cached versions exist", async () => {
+        const exitSpy = vitest_1.vi.fn();
+        const originalExit = process.exit;
+        const updatesModule = await Promise.resolve().then(() => __importStar(require("./updates")));
+        const decideMock = updatesModule.decideVersionToUse;
+        decideMock.mockReturnValueOnce(Promise.resolve({ versionToUse: "0.9.0", fromCache: false }));
+        const githubModule = await Promise.resolve().then(() => __importStar(require("./github")));
+        const getReleaseByVersionSpy = vitest_1.vi
+            .spyOn(githubModule, "getReleaseByVersion")
+            .mockRejectedValueOnce(new Error("boom"));
+        const cacheModule = await Promise.resolve().then(() => __importStar(require("./cache")));
+        const getCachedVersionsSpy = vitest_1.vi
+            .spyOn(cacheModule, "getCachedVersionsForPlatform")
+            .mockReturnValueOnce([]);
+        // @ts-expect-error override for tests
+        process.exit = exitSpy;
+        try {
+            await (0, vitest_1.expect)((0, index_1.runCli)()).rejects.toThrow("boom");
+            (0, vitest_1.expect)(getReleaseByVersionSpy).toHaveBeenCalled();
+            (0, vitest_1.expect)(getCachedVersionsSpy).toHaveBeenCalled();
+            (0, vitest_1.expect)(exitSpy).not.toHaveBeenCalled();
         }
         finally {
             // @ts-expect-error restore original
             process.exit = originalExit;
             getReleaseByVersionSpy.mockRestore();
+            getCachedVersionsSpy.mockRestore();
         }
     });
     (0, vitest_1.it)("falls back to cached version when update check fails", async () => {
@@ -306,4 +415,74 @@ vitest_1.vi.mock("node:child_process", () => {
             ensureBinaryDownloadedMock.mockClear();
         }
     });
+    (0, vitest_1.it)("falls back to redirect when update check is rate-limited and no binaries are cached", async () => {
+        const exitSpy = vitest_1.vi.fn();
+        const originalExit = process.exit;
+        const githubModule = await Promise.resolve().then(() => __importStar(require("./github")));
+        const getLatestReleaseSpy = vitest_1.vi
+            .spyOn(githubModule, "getLatestRelease")
+            .mockRejectedValueOnce(new githubModule.GithubRateLimitError("rate limited", { status: 403 }));
+        const redirectSpy = vitest_1.vi.spyOn(githubModule, "resolveLatestReleaseAssetViaRedirect");
+        const cacheModule = await Promise.resolve().then(() => __importStar(require("./cache")));
+        const getCachedVersionsSpy = vitest_1.vi
+            .spyOn(cacheModule, "getCachedVersionsForPlatform")
+            .mockReturnValueOnce([]);
+        const errorSpy = vitest_1.vi.spyOn(console, "error").mockImplementation(() => { });
+        // @ts-expect-error override for tests
+        process.exit = exitSpy;
+        try {
+            ensureBinaryDownloadedMock.mockClear();
+            await (0, index_1.runCli)();
+            (0, vitest_1.expect)(getLatestReleaseSpy).toHaveBeenCalled();
+            (0, vitest_1.expect)(getCachedVersionsSpy).toHaveBeenCalled();
+            (0, vitest_1.expect)(redirectSpy).toHaveBeenCalled();
+            (0, vitest_1.expect)(ensureBinaryDownloadedMock).toHaveBeenCalledWith(vitest_1.expect.objectContaining({ version: "1.0.0" }));
+            (0, vitest_1.expect)(exitSpy).toHaveBeenCalled();
+        }
+        finally {
+            // @ts-expect-error restore original
+            process.exit = originalExit;
+            getLatestReleaseSpy.mockRestore();
+            redirectSpy.mockRestore();
+            getCachedVersionsSpy.mockRestore();
+            errorSpy.mockRestore();
+            ensureBinaryDownloadedMock.mockClear();
+        }
+    });
+    (0, vitest_1.it)("falls back to redirect download when pinned release lookup is rate-limited", async () => {
+        const exitSpy = vitest_1.vi.fn();
+        const originalExit = process.exit;
+        const argsModule = await Promise.resolve().then(() => __importStar(require("./args")));
+        const parseCliArgsMock = argsModule.parseCliArgs;
+        parseCliArgsMock.mockReturnValueOnce({
+            ...defaultCliOptions,
+            binaryVersion: "v1.2.3",
+        });
+        const githubModule = await Promise.resolve().then(() => __importStar(require("./github")));
+        const getReleaseByVersionSpy = vitest_1.vi
+            .spyOn(githubModule, "getReleaseByVersion")
+            .mockRejectedValueOnce(new githubModule.GithubRateLimitError("rate limited", { status: 403 }));
+        const redirectSpy = vitest_1.vi.spyOn(githubModule, "resolveReleaseAssetViaRedirect");
+        const existsSpy = vitest_1.vi.spyOn(node_fs_1.default, "existsSync").mockReturnValueOnce(false);
+        const errorSpy = vitest_1.vi.spyOn(console, "error").mockImplementation(() => { });
+        // @ts-expect-error override for tests
+        process.exit = exitSpy;
+        try {
+            ensureBinaryDownloadedMock.mockClear();
+            await (0, index_1.runCli)();
+            (0, vitest_1.expect)(getReleaseByVersionSpy).toHaveBeenCalled();
+            (0, vitest_1.expect)(redirectSpy).toHaveBeenCalledWith("owner/repo", "1.2.3", vitest_1.expect.any(Array));
+            (0, vitest_1.expect)(ensureBinaryDownloadedMock).toHaveBeenCalledWith(vitest_1.expect.objectContaining({ version: "1.2.3" }));
+            (0, vitest_1.expect)(exitSpy).toHaveBeenCalled();
+        }
+        finally {
+            // @ts-expect-error restore original
+            process.exit = originalExit;
+            getReleaseByVersionSpy.mockRestore();
+            redirectSpy.mockRestore();
+            existsSpy.mockRestore();
+            errorSpy.mockRestore();
+            ensureBinaryDownloadedMock.mockClear();
+        }
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kanban-ai",
-  "version": "0.19.2",
+  "version": "0.19.3",
   "description": "Thin CLI wrapper that downloads and runs the KanbanAI binary from GitHub releases.",
   "bin": {
     "kanban-ai": "dist/index.js"