@nghyane/arcane 0.1.12 → 0.1.14

package/src/utils/index.ts

@@ -0,0 +1,30 @@
+export { EventBus } from "./event-bus";
+export { getEditorCommand, type OpenInEditorOptions, openInEditor } from "./external-editor";
+export {
+	type FileDisplayMode,
+	type FileDisplayModeSession,
+	resolveFileDisplayMode,
+} from "./file-display-mode";
+export { FrontmatterError, type FrontmatterOptions, parseFrontmatter } from "./frontmatter";
+export { type FuzzyMatch, fuzzyFilter, fuzzyMatch } from "./fuzzy";
+export {
+	addIgnoreRules,
+	addIgnoreRulesSync,
+	createIgnoreMatcher,
+	IGNORE_FILE_NAMES,
+	type IgnoreMatcher,
+	prefixIgnorePattern,
+	shouldIgnore,
+	toPosixPath,
+} from "./ignore-files";
+export { convertToPng } from "./image-convert";
+export {
+	formatDimensionNote,
+	type ImageResizeOptions,
+	type ResizedImage,
+	resizeImage,
+} from "./image-resize";
+export { detectSupportedImageMimeTypeFromFile } from "./mime";
+export { openPath } from "./open";
+export { getOrCreateSnapshot, getSnapshotSourceCommand } from "./shell-snapshot";
+export { printTimings, time } from "./timings";

package/src/utils/tools-manager.ts

@@ -2,7 +2,8 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { logger, ptree, TempDir } from "@nghyane/arcane-utils";
-import { APP_NAME, getToolsDir } from "@nghyane/arcane-utils/dirs";
+import { getToolsDir } from "@nghyane/arcane-utils/dirs";
+import { githubClient } from "../web/github-client";
 
 const TOOLS_DIR = getToolsDir();
 const TOOL_DOWNLOAD_TIMEOUT_MS = 15000;
@@ -120,25 +121,14 @@ export function getToolPath(tool: ToolName): string | null {
 
 // Fetch latest release version from GitHub
 async function getLatestVersion(repo: string, signal?: AbortSignal): Promise<string> {
-	let response: Response;
-	try {
-		response = await fetch(`https://api.github.com/repos/${repo}/releases/latest`, {
-			headers: { "User-Agent": `${APP_NAME}-coding-agent` },
-			signal: ptree.combineSignals(signal, TOOL_METADATA_TIMEOUT_MS),
-		});
-	} catch (err) {
-		if (err instanceof Error && err.name === "AbortError") {
-			throw new Error("GitHub API request timed out");
-		}
-		throw err;
+	const result = await githubClient.request<{ tag_name: string }>(`/repos/${repo}/releases/latest`, {
+		timeout: Math.ceil(TOOL_METADATA_TIMEOUT_MS / 1000),
+		signal,
+	});
+	if (!result.ok) {
+		throw new Error(`GitHub API error: ${result.status}`);
 	}
-
-	if (!response.ok) {
-		throw new Error(`GitHub API error: ${response.status}`);
-	}
-
-	const data = (await response.json()) as { tag_name: string };
-	return data.tag_name.replace(/^v/, "");
+	return (result.data as { tag_name: string }).tag_name.replace(/^v/, "");
 }
 
 // Download a file from URL

package/src/web/github-client.ts

@@ -0,0 +1,290 @@
+import { $env, logger } from "@nghyane/arcane-utils";
+import { $ } from "bun";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+interface GitHubResponse<T = unknown> {
+	data: T;
+	ok: boolean;
+	status: number;
+	rateLimit?: RateLimitInfo;
+}
+
+interface RateLimitInfo {
+	remaining: number;
+	limit: number;
+	reset: number;
+}
+
+interface RequestOptions {
+	timeout?: number;
+	signal?: AbortSignal;
+	accept?: string;
+	mediaType?: string;
+}
+
+interface CacheEntry {
+	etag: string;
+	data: unknown;
+	timestamp: number;
+}
+
+// =============================================================================
+// Auth
+// =============================================================================
+
+let cachedToken: string | undefined;
+let tokenResolved = false;
+
+async function resolveToken(): Promise<string | undefined> {
+	if (tokenResolved) return cachedToken;
+	tokenResolved = true;
+
+	// Env vars first
+	const envToken = $env.GITHUB_TOKEN || $env.GH_TOKEN;
+	if (envToken) {
+		cachedToken = envToken;
+		return cachedToken;
+	}
+
+	// Fallback: gh auth token
+	if (Bun.which("gh")) {
+		try {
+			const result = await $`gh auth token`.quiet().nothrow();
+			if (result.exitCode === 0) {
+				const token = result.text().trim();
+				if (token) {
+					cachedToken = token;
+					return cachedToken;
+				}
+			}
+		} catch {
+			// gh not authenticated
+		}
+	}
+
+	return undefined;
+}
+
+// =============================================================================
+// ETag Cache
+// =============================================================================
+
+const etagCache = new Map<string, CacheEntry>();
+const CACHE_MAX_SIZE = 200;
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+function getCacheKey(endpoint: string): string {
+	return endpoint;
+}
+
+function pruneCache(): void {
+	if (etagCache.size <= CACHE_MAX_SIZE) return;
+	const now = Date.now();
+	for (const [key, entry] of etagCache) {
+		if (now - entry.timestamp > CACHE_TTL_MS) {
+			etagCache.delete(key);
+		}
+	}
+	// If still too large, remove oldest
+	if (etagCache.size > CACHE_MAX_SIZE) {
+		const entries = [...etagCache.entries()].sort((a, b) => a[1].timestamp - b[1].timestamp);
+		const toRemove = entries.slice(0, etagCache.size - CACHE_MAX_SIZE);
+		for (const [key] of toRemove) {
+			etagCache.delete(key);
+		}
+	}
+}
+
+// =============================================================================
+// Core Request
+// =============================================================================
+
+const RETRY_STATUS_CODES = new Set([429, 502, 503]);
+const MAX_RETRIES = 3;
+
+async function request<T = unknown>(endpoint: string, options: RequestOptions = {}): Promise<GitHubResponse<T>> {
+	const { timeout = 30, signal } = options;
+	const token = await resolveToken();
+
+	const headers: Record<string, string> = {
+		Accept: options.accept ?? "application/vnd.github.v3+json",
+		"User-Agent": "arcane-github-tool/1.0",
+	};
+
+	if (token) {
+		headers.Authorization = `Bearer ${token}`;
+	}
+
+	if (options.mediaType) {
+		headers.Accept = options.mediaType;
+	}
+
+	// ETag conditional request
+	const cacheKey = getCacheKey(endpoint);
+	const cached = etagCache.get(cacheKey);
+	if (cached && Date.now() - cached.timestamp < CACHE_TTL_MS) {
+		headers["If-None-Match"] = cached.etag;
+	}
+
+	const url = endpoint.startsWith("https://") ? endpoint : `https://api.github.com${endpoint}`;
+
+	let lastError: Error | undefined;
+
+	for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+		try {
+			const controller = new AbortController();
+			const timeoutId = setTimeout(() => controller.abort(), timeout * 1000);
+
+			// Combine with external signal
+			if (signal?.aborted) {
+				clearTimeout(timeoutId);
+				return { data: null as T, ok: false, status: 0 };
+			}
+
+			const abortHandler = () => controller.abort();
+			signal?.addEventListener("abort", abortHandler, { once: true });
+
+			try {
+				const response = await fetch(url, {
+					headers,
+					signal: controller.signal,
+				});
+
+				clearTimeout(timeoutId);
+				signal?.removeEventListener("abort", abortHandler);
+
+				// Parse rate limit
+				const rateLimit: RateLimitInfo = {
+					remaining: parseInt(response.headers.get("x-ratelimit-remaining") ?? "-1", 10),
+					limit: parseInt(response.headers.get("x-ratelimit-limit") ?? "-1", 10),
+					reset: parseInt(response.headers.get("x-ratelimit-reset") ?? "0", 10),
+				};
+
+				if (rateLimit.remaining >= 0 && rateLimit.remaining < 10) {
+					logger.warn("GitHub API rate limit low", {
+						remaining: rateLimit.remaining,
+						reset: new Date(rateLimit.reset * 1000).toISOString(),
+					});
+				}
+
+				// 304 Not Modified — return cached data
+				if (response.status === 304 && cached) {
+					cached.timestamp = Date.now();
+					return { data: cached.data as T, ok: true, status: 304, rateLimit };
+				}
+
+				// Retry on transient errors
+				if (RETRY_STATUS_CODES.has(response.status) && attempt < MAX_RETRIES) {
+					const retryAfter = response.headers.get("retry-after");
+					const waitMs = retryAfter ? parseInt(retryAfter, 10) * 1000 : Math.min(1000 * 2 ** attempt, 10_000);
+
+					if (response.status === 429 && rateLimit.remaining === 0) {
+						const resetMs = rateLimit.reset * 1000 - Date.now();
+						if (resetMs > 30_000) {
+							return { data: null as T, ok: false, status: response.status, rateLimit };
+						}
+						await Bun.sleep(Math.max(resetMs, 1000));
+					} else {
+						await Bun.sleep(waitMs);
+					}
+					continue;
+				}
+
+				if (!response.ok) {
+					return { data: null as T, ok: false, status: response.status, rateLimit };
+				}
+
+				const data = (await response.json()) as T;
+
+				// Cache with ETag
+				const etag = response.headers.get("etag");
+				if (etag) {
+					etagCache.set(cacheKey, { etag, data, timestamp: Date.now() });
+					pruneCache();
+				}
+
+				return { data, ok: true, status: response.status, rateLimit };
+			} catch (err) {
+				clearTimeout(timeoutId);
+				signal?.removeEventListener("abort", abortHandler);
+				throw err;
+			}
+		} catch (err) {
+			lastError = err instanceof Error ? err : new Error(String(err));
+			if (attempt < MAX_RETRIES) {
+				await Bun.sleep(1000 * 2 ** attempt);
+			}
+		}
+	}
+
+	logger.error("GitHub API request failed", { endpoint, error: lastError?.message });
+	return { data: null as T, ok: false, status: 0 };
+}
+
+// =============================================================================
+// Paginated Request
+// =============================================================================
+
+async function requestPaginated<T>(
+	endpoint: string,
+	options: RequestOptions & { perPage?: number; maxPages?: number } = {},
+): Promise<GitHubResponse<T[]>> {
+	const perPage = options.perPage ?? 30;
+	const maxPages = options.maxPages ?? 3;
+	const separator = endpoint.includes("?") ? "&" : "?";
+	const allData: T[] = [];
+
+	for (let page = 1; page <= maxPages; page++) {
+		const paginatedEndpoint = `${endpoint}${separator}per_page=${perPage}&page=${page}`;
+		const response = await request<T[]>(paginatedEndpoint, options);
+
+		if (!response.ok) {
+			if (allData.length > 0) {
+				return { data: allData, ok: true, status: response.status, rateLimit: response.rateLimit };
+			}
+			return response;
+		}
+
+		allData.push(...response.data);
+
+		// No more pages
+		if (response.data.length < perPage) break;
+	}
+
+	return { data: allData, ok: true, status: 200 };
+}
+
+// =============================================================================
+// Raw content request (for file contents)
+// =============================================================================
+
+async function requestRaw(endpoint: string, options: RequestOptions = {}): Promise<GitHubResponse<string>> {
+	return request<string>(endpoint, {
+		...options,
+		mediaType: "application/vnd.github.v3.raw",
+	});
+}
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+export const githubClient = {
+	request,
+	requestPaginated,
+	requestRaw,
+	resolveToken,
+
+	clearCache(): void {
+		etagCache.clear();
+	},
+
+	isAuthenticated(): Promise<boolean> {
+		return resolveToken().then(t => t !== undefined);
+	},
+} as const;
+
+export type { GitHubResponse, RateLimitInfo, RequestOptions };

package/src/web/scrapers/github.ts

@@ -1,4 +1,4 @@
-import { $env, ptree } from "@nghyane/arcane-utils";
+import { githubClient } from "../github-client";
 import type { RenderResult, SpecialHandler } from "./types";
 import { finalizeOutput, loadPage } from "./types";
 
@@ -11,12 +11,6 @@ interface GitHubUrl {
 	number?: number;
 }
 
-interface GitHubIssueComment {
-	user: { login: string };
-	created_at: string;
-	body: string;
-}
-
 /**
  * Parse GitHub URL into components
  */
@@ -75,40 +69,15 @@ function toRawGitHubUrl(gh: GitHubUrl): string {
 }
 
 /**
- * Fetch from GitHub API
+ * Fetch from GitHub API — delegates to shared github-client.
  */
 export async function fetchGitHubApi(
 	endpoint: string,
 	timeout: number,
 	signal?: AbortSignal,
 ): Promise<{ data: unknown; ok: boolean }> {
-	try {
-		const requestSignal = ptree.combineSignals(signal, timeout * 1000);
-
-		const headers: Record<string, string> = {
-			Accept: "application/vnd.github.v3+json",
-			"User-Agent": "arc-web-fetch/1.0",
-		};
-
-		// Use GITHUB_TOKEN if available
-		const token = $env.GITHUB_TOKEN || $env.GH_TOKEN;
-		if (token) {
-			headers.Authorization = `Bearer ${token}`;
-		}
-
-		const response = await fetch(`https://api.github.com${endpoint}`, {
-			signal: requestSignal,
-			headers,
-		});
-
-		if (!response.ok) {
-			return { data: null, ok: false };
-		}
-
-		return { data: await response.json(), ok: true };
-	} catch {
-		return { data: null, ok: false };
-	}
+	const result = await githubClient.request(endpoint, { timeout, signal });
+	return { data: result.data, ok: result.ok };
 }
 
 /**
@@ -118,35 +87,15 @@ async function fetchGitHubIssueComments(
 	owner: string,
 	repo: string,
 	issueNumber: number,
-	expectedCount: number,
+	_expectedCount: number,
 	timeout: number,
 	signal?: AbortSignal,
-): Promise<GitHubIssueComment[]> {
-	const perPage = 100;
-	const comments: GitHubIssueComment[] = [];
-
-	for (let page = 1; comments.length < expectedCount; page++) {
-		const result = await fetchGitHubApi(
-			`/repos/${owner}/${repo}/issues/${issueNumber}/comments?per_page=${perPage}&page=${page}`,
-			timeout,
-			signal,
-		);
-		if (!result.ok || !Array.isArray(result.data)) {
-			break;
-		}
-
-		const pageComments = result.data as GitHubIssueComment[];
-		if (pageComments.length === 0) {
-			break;
-		}
-
-		comments.push(...pageComments);
-		if (pageComments.length < perPage) {
-			break;
-		}
-	}
-
-	return comments;
+): Promise<Array<{ user: { login: string }; created_at: string; body: string }>> {
+	const result = await githubClient.requestPaginated<{ user: { login: string }; created_at: string; body: string }>(
+		`/repos/${owner}/${repo}/issues/${issueNumber}/comments`,
+		{ timeout, signal, perPage: 100, maxPages: 5 },
+	);
+	return result.ok ? result.data : [];
 }
 
 /**

package/src/web/search/auth.ts

@@ -23,9 +23,7 @@ const DEFAULT_BASE_URL = "https://api.anthropic.com";
  */
 async function readJson<T>(filePath: string): Promise<T | null> {
 	try {
-		const file = Bun.file(filePath);
-		if (!(await file.exists())) return null;
-		const content = await file.text();
+		const content = await Bun.file(filePath).text();
 		return JSON.parse(content) as T;
 	} catch (error) {
 		logger.warn("Failed to parse JSON file", { path: filePath, error: String(error) });