@bastani/atomic 0.8.31-alpha.5 → 0.9.0-alpha.1

package/dist/builtin/web-access/extract-frames.ts

@@ -0,0 +1,228 @@
+import { extractYouTubeFrame, extractYouTubeFrames, getYouTubeStreamInfo, isYouTubeURL } from "./youtube-extract.js";
+import { extractVideoFrame, getLocalVideoDuration, isVideoFile } from "./video-extract.js";
+import { formatSeconds } from "./utils.js";
+import type { ExtractedContent, ExtractOptions, VideoFrame } from "./extract.js";
+
+function errorMessage(err: unknown): string {
+	return err instanceof Error ? err.message : String(err);
+}
+
+function parseTimestamp(ts: string): number | null {
+	const num = Number(ts);
+	if (!isNaN(num) && num >= 0) return Math.floor(num);
+	const parts = ts.split(":").map(Number);
+	if (parts.some(p => isNaN(p) || p < 0)) return null;
+	if (parts.length === 3) return Math.floor(parts[0] * 3600 + parts[1] * 60 + parts[2]);
+	if (parts.length === 2) return Math.floor(parts[0] * 60 + parts[1]);
+	return null;
+}
+
+type TimestampSpec = { type: "single"; seconds: number } | { type: "range"; start: number; end: number };
+
+function parseTimestampSpec(ts: string): TimestampSpec | null {
+	const dashIdx = ts.indexOf("-", 1);
+	if (dashIdx > 0) {
+		const start = parseTimestamp(ts.slice(0, dashIdx));
+		const end = parseTimestamp(ts.slice(dashIdx + 1));
+		if (start !== null && end !== null && end > start) return { type: "range", start, end };
+	}
+	const seconds = parseTimestamp(ts);
+	return seconds !== null ? { type: "single", seconds } : null;
+}
+
+const DEFAULT_RANGE_FRAMES = 6;
+const MIN_FRAME_INTERVAL = 5;
+
+function computeRangeTimestamps(start: number, end: number, maxFrames: number = DEFAULT_RANGE_FRAMES): number[] {
+	if (maxFrames <= 1) return [start];
+	const duration = end - start;
+	const idealInterval = duration / (maxFrames - 1);
+	if (idealInterval < MIN_FRAME_INTERVAL) {
+		const timestamps: number[] = [];
+		for (let t = start; t <= end && timestamps.length < maxFrames; t += MIN_FRAME_INTERVAL) {
+			timestamps.push(t);
+		}
+		return timestamps;
+	}
+	return Array.from({ length: maxFrames }, (_, i) => Math.round(start + i * idealInterval));
+}
+
+function buildFrameResult(
+	url: string, label: string, requestedCount: number,
+	frames: VideoFrame[], error: string | null, duration?: number,
+): ExtractedContent {
+	if (frames.length === 0) {
+		const msg = error ?? "Frame extraction failed";
+		return { url, title: `Frames ${label} (0/${requestedCount})`, content: msg, error: msg };
+	}
+	return {
+		url,
+		title: `Frames ${label} (${frames.length}/${requestedCount})`,
+		content: `${frames.length} frames extracted from ${label}`,
+		error: null,
+		frames,
+		duration,
+	};
+}
+
+async function extractLocalFrames(
+	filePath: string, timestamps: number[],
+): Promise<{ frames: VideoFrame[]; error: string | null }> {
+	const results = await Promise.all(timestamps.map(async (t) => {
+		const frame = await extractVideoFrame(filePath, t);
+		if ("error" in frame) return { error: frame.error };
+		return { ...frame, timestamp: formatSeconds(t) };
+	}));
+	const frames = results.filter((f): f is VideoFrame => "data" in f);
+	const firstError = results.find((f): f is { error: string } => "error" in f);
+	return { frames, error: frames.length === 0 && firstError ? firstError.error : null };
+}
+
+function safeVideoInfo(url: string): { info: ReturnType<typeof isVideoFile>; error?: string } {
+	try {
+		return { info: isVideoFile(url) };
+	} catch (err) {
+		return { info: null, error: errorMessage(err) };
+	}
+}
+
+export async function extractRequestedFrames(
+	url: string,
+	options?: ExtractOptions,
+): Promise<ExtractedContent | null> {
+	if (options?.frames && !options.timestamp) {
+		const frameCount = options.frames;
+		const ytInfo = isYouTubeURL(url);
+		if (ytInfo.isYouTube && ytInfo.videoId) {
+			const streamInfo = await getYouTubeStreamInfo(ytInfo.videoId);
+			if ("error" in streamInfo) {
+				return { url, title: "Frames", content: streamInfo.error, error: streamInfo.error };
+			}
+			if (streamInfo.duration === null) {
+				const error = "Cannot determine video duration. Use a timestamp range instead.";
+				return { url, title: "Frames", content: error, error };
+			}
+			const dur = Math.floor(streamInfo.duration);
+			const timestamps = computeRangeTimestamps(0, dur, frameCount);
+			const result = await extractYouTubeFrames(ytInfo.videoId, timestamps, streamInfo);
+			const label = `${formatSeconds(0)}-${formatSeconds(dur)}`;
+			return buildFrameResult(url, label, timestamps.length, result.frames, result.error, streamInfo.duration);
+		}
+
+		const localVideo = safeVideoInfo(url);
+		if (localVideo.error) {
+			return { url, title: "", content: "", error: localVideo.error };
+		}
+		if (localVideo.info) {
+			const durationResult = await getLocalVideoDuration(localVideo.info.absolutePath);
+			if (typeof durationResult !== "number") {
+				return { url, title: "Frames", content: durationResult.error, error: durationResult.error };
+			}
+			const dur = Math.floor(durationResult);
+			const timestamps = computeRangeTimestamps(0, dur, frameCount);
+			const result = await extractLocalFrames(localVideo.info.absolutePath, timestamps);
+			const label = `${formatSeconds(0)}-${formatSeconds(dur)}`;
+			return buildFrameResult(url, label, timestamps.length, result.frames, result.error, durationResult);
+		}
+
+		return { url, title: "", content: "", error: "Frame extraction only works with YouTube and local video files" };
+	}
+
+	if (options?.timestamp) {
+		const spec = parseTimestampSpec(options.timestamp);
+		if (!spec) {
+			return {
+				url,
+				title: "",
+				content: "",
+				error: `Invalid timestamp format: "${options.timestamp}". Use "H:MM:SS", "MM:SS", "85", or "start-end".`,
+			};
+		}
+
+		const frameCount = options.frames;
+		const ytInfo = isYouTubeURL(url);
+		if (ytInfo.isYouTube && ytInfo.videoId) {
+			const streamInfo = await getYouTubeStreamInfo(ytInfo.videoId);
+			if ("error" in streamInfo) {
+				if (spec.type === "range") {
+					const label = `${formatSeconds(spec.start)}-${formatSeconds(spec.end)}`;
+					return { url, title: `Frames ${label}`, content: streamInfo.error, error: streamInfo.error };
+				}
+				if (frameCount) {
+					const end = spec.seconds + (frameCount - 1) * MIN_FRAME_INTERVAL;
+					const label = `${formatSeconds(spec.seconds)}-${formatSeconds(end)}`;
+					return { url, title: `Frames ${label}`, content: streamInfo.error, error: streamInfo.error };
+				}
+				return { url, title: `Frame at ${options.timestamp}`, content: streamInfo.error, error: streamInfo.error };
+			}
+
+			if (spec.type === "range") {
+				const label = `${formatSeconds(spec.start)}-${formatSeconds(spec.end)}`;
+				if (streamInfo.duration !== null && spec.end > streamInfo.duration) {
+					const error = `Timestamp ${formatSeconds(spec.end)} exceeds video duration (${formatSeconds(Math.floor(streamInfo.duration))})`;
+					return { url, title: `Frames ${label}`, content: error, error };
+				}
+				const timestamps = frameCount
+					? computeRangeTimestamps(spec.start, spec.end, frameCount)
+					: computeRangeTimestamps(spec.start, spec.end);
+				const result = await extractYouTubeFrames(ytInfo.videoId, timestamps, streamInfo);
+				return buildFrameResult(url, label, timestamps.length, result.frames, result.error, result.duration ?? undefined);
+			}
+
+			if (frameCount) {
+				const end = spec.seconds + (frameCount - 1) * MIN_FRAME_INTERVAL;
+				const label = `${formatSeconds(spec.seconds)}-${formatSeconds(end)}`;
+				if (streamInfo.duration !== null && end > streamInfo.duration) {
+					const error = `Timestamp ${formatSeconds(end)} exceeds video duration (${formatSeconds(Math.floor(streamInfo.duration))})`;
+					return { url, title: `Frames ${label}`, content: error, error };
+				}
+				const timestamps = computeRangeTimestamps(spec.seconds, end, frameCount);
+				const result = await extractYouTubeFrames(ytInfo.videoId, timestamps, streamInfo);
+				return buildFrameResult(url, label, timestamps.length, result.frames, result.error, result.duration ?? undefined);
+			}
+
+			if (streamInfo.duration !== null && spec.seconds > streamInfo.duration) {
+				const error = `Timestamp ${formatSeconds(spec.seconds)} exceeds video duration (${formatSeconds(Math.floor(streamInfo.duration))})`;
+				return { url, title: `Frame at ${options.timestamp}`, content: error, error };
+			}
+			const frame = await extractYouTubeFrame(ytInfo.videoId, spec.seconds, streamInfo);
+			if ("error" in frame) {
+				return { url, title: `Frame at ${options.timestamp}`, content: frame.error, error: frame.error };
+			}
+			return { url, title: `Frame at ${options.timestamp}`, content: `Video frame at ${options.timestamp}`, error: null, thumbnail: frame };
+		}
+
+		const localVideo = safeVideoInfo(url);
+		if (localVideo.error) {
+			return { url, title: "", content: "", error: localVideo.error };
+		}
+		if (localVideo.info) {
+			if (spec.type === "range") {
+				const timestamps = frameCount
+					? computeRangeTimestamps(spec.start, spec.end, frameCount)
+					: computeRangeTimestamps(spec.start, spec.end);
+				const result = await extractLocalFrames(localVideo.info.absolutePath, timestamps);
+				const label = `${formatSeconds(spec.start)}-${formatSeconds(spec.end)}`;
+				return buildFrameResult(url, label, timestamps.length, result.frames, result.error);
+			}
+
+			if (frameCount) {
+				const end = spec.seconds + (frameCount - 1) * MIN_FRAME_INTERVAL;
+				const timestamps = computeRangeTimestamps(spec.seconds, end, frameCount);
+				const result = await extractLocalFrames(localVideo.info.absolutePath, timestamps);
+				const label = `${formatSeconds(spec.seconds)}-${formatSeconds(end)}`;
+				return buildFrameResult(url, label, timestamps.length, result.frames, result.error);
+			}
+
+			const frame = await extractVideoFrame(localVideo.info.absolutePath, spec.seconds);
+			if ("error" in frame) {
+				return { url, title: `Frame at ${options.timestamp}`, content: frame.error, error: frame.error };
+			}
+			return { url, title: `Frame at ${options.timestamp}`, content: `Video frame at ${options.timestamp}`, error: null, thumbnail: frame };
+		}
+
+		return { url, title: "", content: "", error: "Timestamp extraction only works with YouTube and local video files" };
+	}
+
+	return null;
+}

package/dist/builtin/web-access/extract.ts

@@ -7,10 +7,10 @@ import { activityMonitor } from "./activity.js";
 import { extractRSCContent } from "./rsc-extract.js";
 import { extractPDFToMarkdown, isPDF } from "./pdf-extract.js";
 import { extractGitHub } from "./github-extract.js";
-import { isYouTubeURL, isYouTubeEnabled, extractYouTube, extractYouTubeFrame, extractYouTubeFrames, getYouTubeStreamInfo } from "./youtube-extract.js";
+import { isYouTubeURL, isYouTubeEnabled, extractYouTube } from "./youtube-extract.js";
 import { extractWithUrlContext, extractWithGeminiWeb } from "./gemini-url-context.js";
-import { isVideoFile, extractVideo, extractVideoFrame, getLocalVideoDuration } from "./video-extract.js";
-import { formatSeconds } from "./utils.js";
+import { isVideoFile, extractVideo } from "./video-extract.js";
+import { extractRequestedFrames } from "./extract-frames.js";
 
 const DEFAULT_TIMEOUT_MS = 30000;
 const CONCURRENT_LIMIT = 3;
@@ -34,6 +34,14 @@ function abortedResult(url: string): ExtractedContent {
 	return { url, title: "", content: "", error: "Aborted" };
 }
 
+function safeVideoInfo(url: string): { info: ReturnType<typeof isVideoFile>; error?: string } {
+	try {
+		return { info: isVideoFile(url) };
+	} catch (err) {
+		return { info: null, error: errorMessage(err) };
+	}
+}
+
 const turndown = new TurndownService({
 	headingStyle: "atx",
 	codeBlockStyle: "fenced",
@@ -127,84 +135,6 @@ async function extractWithJinaReader(
 	}
 }
 
-function parseTimestamp(ts: string): number | null {
-	const num = Number(ts);
-	if (!isNaN(num) && num >= 0) return Math.floor(num);
-	const parts = ts.split(":").map(Number);
-	if (parts.some(p => isNaN(p) || p < 0)) return null;
-	if (parts.length === 3) return Math.floor(parts[0] * 3600 + parts[1] * 60 + parts[2]);
-	if (parts.length === 2) return Math.floor(parts[0] * 60 + parts[1]);
-	return null;
-}
-
-type TimestampSpec = { type: "single"; seconds: number } | { type: "range"; start: number; end: number };
-
-function parseTimestampSpec(ts: string): TimestampSpec | null {
-	const dashIdx = ts.indexOf("-", 1);
-	if (dashIdx > 0) {
-		const start = parseTimestamp(ts.slice(0, dashIdx));
-		const end = parseTimestamp(ts.slice(dashIdx + 1));
-		if (start !== null && end !== null && end > start) return { type: "range", start, end };
-	}
-	const seconds = parseTimestamp(ts);
-	return seconds !== null ? { type: "single", seconds } : null;
-}
-
-const DEFAULT_RANGE_FRAMES = 6;
-const MIN_FRAME_INTERVAL = 5;
-
-function computeRangeTimestamps(start: number, end: number, maxFrames: number = DEFAULT_RANGE_FRAMES): number[] {
-	if (maxFrames <= 1) return [start];
-	const duration = end - start;
-	const idealInterval = duration / (maxFrames - 1);
-	if (idealInterval < MIN_FRAME_INTERVAL) {
-		const timestamps: number[] = [];
-		for (let t = start; t <= end && timestamps.length < maxFrames; t += MIN_FRAME_INTERVAL) {
-			timestamps.push(t);
-		}
-		return timestamps;
-	}
-	return Array.from({ length: maxFrames }, (_, i) => Math.round(start + i * idealInterval));
-}
-
-function buildFrameResult(
-	url: string, label: string, requestedCount: number,
-	frames: VideoFrame[], error: string | null, duration?: number,
-): ExtractedContent {
-	if (frames.length === 0) {
-		const msg = error ?? "Frame extraction failed";
-		return { url, title: `Frames ${label} (0/${requestedCount})`, content: msg, error: msg };
-	}
-	return {
-		url,
-		title: `Frames ${label} (${frames.length}/${requestedCount})`,
-		content: `${frames.length} frames extracted from ${label}`,
-		error: null,
-		frames,
-		duration,
-	};
-}
-
-async function extractLocalFrames(
-	filePath: string, timestamps: number[],
-): Promise<{ frames: VideoFrame[]; error: string | null }> {
-	const results = await Promise.all(timestamps.map(async (t) => {
-		const frame = await extractVideoFrame(filePath, t);
-		if ("error" in frame) return { error: frame.error };
-		return { ...frame, timestamp: formatSeconds(t) };
-	}));
-	const frames = results.filter((f): f is VideoFrame => "data" in f);
-	const firstError = results.find((f): f is { error: string } => "error" in f);
-	return { frames, error: frames.length === 0 && firstError ? firstError.error : null };
-}
-
-function safeVideoInfo(url: string): { info: ReturnType<typeof isVideoFile>; error?: string } {
-	try {
-		return { info: isVideoFile(url) };
-	} catch (err) {
-		return { info: null, error: errorMessage(err) };
-	}
-}
 
 export async function extractContent(
 	url: string,
@@ -215,139 +145,8 @@ export async function extractContent(
 		return { url, title: "", content: "", error: "Aborted" };
 	}
 
-	if (options?.frames && !options.timestamp) {
-		const frameCount = options.frames;
-		const ytInfo = isYouTubeURL(url);
-		if (ytInfo.isYouTube && ytInfo.videoId) {
-			const streamInfo = await getYouTubeStreamInfo(ytInfo.videoId);
-			if ("error" in streamInfo) {
-				return { url, title: "Frames", content: streamInfo.error, error: streamInfo.error };
-			}
-			if (streamInfo.duration === null) {
-				const error = "Cannot determine video duration. Use a timestamp range instead.";
-				return { url, title: "Frames", content: error, error };
-			}
-			const dur = Math.floor(streamInfo.duration);
-			const timestamps = computeRangeTimestamps(0, dur, frameCount);
-			const result = await extractYouTubeFrames(ytInfo.videoId, timestamps, streamInfo);
-			const label = `${formatSeconds(0)}-${formatSeconds(dur)}`;
-			return buildFrameResult(url, label, timestamps.length, result.frames, result.error, streamInfo.duration);
-		}
-
-		const localVideo = safeVideoInfo(url);
-		if (localVideo.error) {
-			return { url, title: "", content: "", error: localVideo.error };
-		}
-		if (localVideo.info) {
-			const durationResult = await getLocalVideoDuration(localVideo.info.absolutePath);
-			if (typeof durationResult !== "number") {
-				return { url, title: "Frames", content: durationResult.error, error: durationResult.error };
-			}
-			const dur = Math.floor(durationResult);
-			const timestamps = computeRangeTimestamps(0, dur, frameCount);
-			const result = await extractLocalFrames(localVideo.info.absolutePath, timestamps);
-			const label = `${formatSeconds(0)}-${formatSeconds(dur)}`;
-			return buildFrameResult(url, label, timestamps.length, result.frames, result.error, durationResult);
-		}
-
-		return { url, title: "", content: "", error: "Frame extraction only works with YouTube and local video files" };
-	}
-
-	if (options?.timestamp) {
-		const spec = parseTimestampSpec(options.timestamp);
-		if (!spec) {
-			return {
-				url,
-				title: "",
-				content: "",
-				error: `Invalid timestamp format: "${options.timestamp}". Use "H:MM:SS", "MM:SS", "85", or "start-end".`,
-			};
-		}
-
-		const frameCount = options.frames;
-		const ytInfo = isYouTubeURL(url);
-		if (ytInfo.isYouTube && ytInfo.videoId) {
-			const streamInfo = await getYouTubeStreamInfo(ytInfo.videoId);
-			if ("error" in streamInfo) {
-				if (spec.type === "range") {
-					const label = `${formatSeconds(spec.start)}-${formatSeconds(spec.end)}`;
-					return { url, title: `Frames ${label}`, content: streamInfo.error, error: streamInfo.error };
-				}
-				if (frameCount) {
-					const end = spec.seconds + (frameCount - 1) * MIN_FRAME_INTERVAL;
-					const label = `${formatSeconds(spec.seconds)}-${formatSeconds(end)}`;
-					return { url, title: `Frames ${label}`, content: streamInfo.error, error: streamInfo.error };
-				}
-				return { url, title: `Frame at ${options.timestamp}`, content: streamInfo.error, error: streamInfo.error };
-			}
-
-			if (spec.type === "range") {
-				const label = `${formatSeconds(spec.start)}-${formatSeconds(spec.end)}`;
-				if (streamInfo.duration !== null && spec.end > streamInfo.duration) {
-					const error = `Timestamp ${formatSeconds(spec.end)} exceeds video duration (${formatSeconds(Math.floor(streamInfo.duration))})`;
-					return { url, title: `Frames ${label}`, content: error, error };
-				}
-				const timestamps = frameCount
-					? computeRangeTimestamps(spec.start, spec.end, frameCount)
-					: computeRangeTimestamps(spec.start, spec.end);
-				const result = await extractYouTubeFrames(ytInfo.videoId, timestamps, streamInfo);
-				return buildFrameResult(url, label, timestamps.length, result.frames, result.error, result.duration ?? undefined);
-			}
-
-			if (frameCount) {
-				const end = spec.seconds + (frameCount - 1) * MIN_FRAME_INTERVAL;
-				const label = `${formatSeconds(spec.seconds)}-${formatSeconds(end)}`;
-				if (streamInfo.duration !== null && end > streamInfo.duration) {
-					const error = `Timestamp ${formatSeconds(end)} exceeds video duration (${formatSeconds(Math.floor(streamInfo.duration))})`;
-					return { url, title: `Frames ${label}`, content: error, error };
-				}
-				const timestamps = computeRangeTimestamps(spec.seconds, end, frameCount);
-				const result = await extractYouTubeFrames(ytInfo.videoId, timestamps, streamInfo);
-				return buildFrameResult(url, label, timestamps.length, result.frames, result.error, result.duration ?? undefined);
-			}
-
-			if (streamInfo.duration !== null && spec.seconds > streamInfo.duration) {
-				const error = `Timestamp ${formatSeconds(spec.seconds)} exceeds video duration (${formatSeconds(Math.floor(streamInfo.duration))})`;
-				return { url, title: `Frame at ${options.timestamp}`, content: error, error };
-			}
-			const frame = await extractYouTubeFrame(ytInfo.videoId, spec.seconds, streamInfo);
-			if ("error" in frame) {
-				return { url, title: `Frame at ${options.timestamp}`, content: frame.error, error: frame.error };
-			}
-			return { url, title: `Frame at ${options.timestamp}`, content: `Video frame at ${options.timestamp}`, error: null, thumbnail: frame };
-		}
-
-		const localVideo = safeVideoInfo(url);
-		if (localVideo.error) {
-			return { url, title: "", content: "", error: localVideo.error };
-		}
-		if (localVideo.info) {
-			if (spec.type === "range") {
-				const timestamps = frameCount
-					? computeRangeTimestamps(spec.start, spec.end, frameCount)
-					: computeRangeTimestamps(spec.start, spec.end);
-				const result = await extractLocalFrames(localVideo.info.absolutePath, timestamps);
-				const label = `${formatSeconds(spec.start)}-${formatSeconds(spec.end)}`;
-				return buildFrameResult(url, label, timestamps.length, result.frames, result.error);
-			}
-
-			if (frameCount) {
-				const end = spec.seconds + (frameCount - 1) * MIN_FRAME_INTERVAL;
-				const timestamps = computeRangeTimestamps(spec.seconds, end, frameCount);
-				const result = await extractLocalFrames(localVideo.info.absolutePath, timestamps);
-				const label = `${formatSeconds(spec.seconds)}-${formatSeconds(end)}`;
-				return buildFrameResult(url, label, timestamps.length, result.frames, result.error);
-			}
-
-			const frame = await extractVideoFrame(localVideo.info.absolutePath, spec.seconds);
-			if ("error" in frame) {
-				return { url, title: `Frame at ${options.timestamp}`, content: frame.error, error: frame.error };
-			}
-			return { url, title: `Frame at ${options.timestamp}`, content: `Video frame at ${options.timestamp}`, error: null, thumbnail: frame };
-		}
-
-		return { url, title: "", content: "", error: "Timestamp extraction only works with YouTube and local video files" };
-	}
+	const frameResult = await extractRequestedFrames(url, options);
+	if (frameResult) return frameResult;
 
 	const localVideo = safeVideoInfo(url);
 	if (localVideo.error) {

package/dist/builtin/web-access/github-config.ts

@@ -0,0 +1,156 @@
+import { existsSync, readFileSync } from "node:fs";
+import { findReadableConfigPath } from "./config-paths.ts";
+
+const CONFIG_PATH = findReadableConfigPath();
+
+export const BINARY_EXTENSIONS = new Set([
+	".png", ".jpg", ".jpeg", ".gif", ".bmp", ".ico", ".webp", ".svg", ".tiff", ".tif",
+	".mp3", ".mp4", ".avi", ".mov", ".mkv", ".flv", ".wmv", ".wav", ".ogg", ".webm", ".flac", ".aac",
+	".zip", ".tar", ".gz", ".bz2", ".xz", ".7z", ".rar", ".zst",
+	".exe", ".dll", ".so", ".dylib", ".bin", ".o", ".a", ".lib",
+	".woff", ".woff2", ".ttf", ".otf", ".eot",
+	".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx",
+	".sqlite", ".db", ".sqlite3",
+	".pyc", ".pyo", ".class", ".jar", ".war",
+	".iso", ".img", ".dmg",
+]);
+
+export const NOISE_DIRS = new Set([
+	"node_modules", "vendor", ".next", "dist", "build", "__pycache__",
+	".venv", "venv", ".tox", ".mypy_cache", ".pytest_cache",
+	"target", ".gradle", ".idea", ".vscode",
+]);
+
+export const MAX_INLINE_FILE_CHARS = 100_000;
+export const MAX_TREE_ENTRIES = 200;
+
+export interface GitHubUrlInfo {
+	owner: string;
+	repo: string;
+	ref?: string;
+	refIsFullSha: boolean;
+	path?: string;
+	type: "root" | "blob" | "tree";
+}
+
+export interface GitHubCloneConfig {
+	enabled: boolean;
+	maxRepoSizeMB: number;
+	cloneTimeoutSeconds: number;
+	clonePath: string;
+}
+
+let cachedConfig: GitHubCloneConfig | null = null;
+
+function normalizeEnabled(value: unknown, fallback: boolean): boolean {
+	return typeof value === "boolean" ? value : fallback;
+}
+
+function normalizePositiveNumber(value: unknown, fallback: number): number {
+	if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+	return value > 0 ? value : fallback;
+}
+
+function normalizeClonePath(value: unknown, fallback: string): string {
+	if (typeof value !== "string") return fallback;
+	const normalized = value.trim();
+	return normalized.length > 0 ? normalized : fallback;
+}
+
+export function loadGitHubConfig(): GitHubCloneConfig {
+	if (cachedConfig) return cachedConfig;
+
+	const defaults: GitHubCloneConfig = {
+		enabled: true,
+		maxRepoSizeMB: 350,
+		cloneTimeoutSeconds: 30,
+		clonePath: "/tmp/atomic-github-repos",
+	};
+
+	if (!existsSync(CONFIG_PATH)) {
+		cachedConfig = defaults;
+		return cachedConfig;
+	}
+
+	const rawText = readFileSync(CONFIG_PATH, "utf-8");
+	let raw: { githubClone?: { enabled?: unknown; maxRepoSizeMB?: unknown; cloneTimeoutSeconds?: unknown; clonePath?: unknown } };
+	try {
+		raw = JSON.parse(rawText) as { githubClone?: { enabled?: unknown; maxRepoSizeMB?: unknown; cloneTimeoutSeconds?: unknown; clonePath?: unknown } };
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to parse ${CONFIG_PATH}: ${message}`);
+	}
+
+	const gc = raw.githubClone ?? {};
+	cachedConfig = {
+		enabled: normalizeEnabled(gc.enabled, defaults.enabled),
+		maxRepoSizeMB: normalizePositiveNumber(gc.maxRepoSizeMB, defaults.maxRepoSizeMB),
+		cloneTimeoutSeconds: normalizePositiveNumber(gc.cloneTimeoutSeconds, defaults.cloneTimeoutSeconds),
+		clonePath: normalizeClonePath(gc.clonePath, defaults.clonePath),
+	};
+	return cachedConfig;
+}
+
+const NON_CODE_SEGMENTS = new Set([
+	"issues", "pull", "pulls", "discussions", "releases", "wiki",
+	"actions", "settings", "security", "projects", "graphs",
+	"compare", "commits", "tags", "branches", "stargazers",
+	"watchers", "network", "forks", "milestone", "labels",
+	"packages", "codespaces", "contribute", "community",
+	"sponsors", "invitations", "notifications", "insights",
+]);
+
+export function parseGitHubUrl(url: string): GitHubUrlInfo | null {
+	let parsed: URL;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return null;
+	}
+
+	const host = parsed.hostname.toLowerCase();
+	if (host !== "github.com" && host !== "www.github.com") return null;
+
+	const segments = parsed.pathname
+		.split("/")
+		.filter(Boolean)
+		.map((segment) => {
+			try {
+				return decodeURIComponent(segment);
+			} catch {
+				return segment;
+			}
+		});
+	if (segments.length < 2) return null;
+
+	const owner = segments[0];
+	const repo = segments[1].replace(/\.git$/, "");
+
+	if (NON_CODE_SEGMENTS.has(segments[2]?.toLowerCase())) return null;
+
+	if (segments.length === 2) {
+		return { owner, repo, refIsFullSha: false, type: "root" };
+	}
+
+	const action = segments[2];
+	if (action !== "blob" && action !== "tree") return null;
+	if (segments.length < 4) return null;
+
+	const ref = segments[3];
+	const refIsFullSha = /^[0-9a-f]{40}$/.test(ref);
+	const pathParts = segments.slice(4);
+	const path = pathParts.length > 0 ? pathParts.join("/") : "";
+
+	return {
+		owner,
+		repo,
+		ref,
+		refIsFullSha,
+		path,
+		type: action as "blob" | "tree",
+	};
+}
+
+export function resetGitHubConfig(): void {
+	cachedConfig = null;
+}