@oh-my-pi/pi-coding-agent 3.25.0 → 3.31.0

package/src/core/tools/web-scrapers/musicbrainz.ts

@@ -0,0 +1,273 @@
+/**
+ * MusicBrainz URL handler for artists, releases, and recordings
+ */
+
+import type { RenderResult, SpecialHandler } from "./types";
+import { finalizeOutput, loadPage } from "./types";
+
+type MusicBrainzEntity = "artist" | "release" | "recording";
+
+interface MusicBrainzLifeSpan {
+	begin?: string;
+	end?: string;
+	ended?: boolean;
+}
+
+interface MusicBrainzArtist {
+	id: string;
+	name: string;
+	type?: string;
+	country?: string;
+	"life-span"?: MusicBrainzLifeSpan;
+}
+
+interface MusicBrainzArtistCredit {
+	name?: string;
+	artist?: {
+		id?: string;
+		name: string;
+	};
+}
+
+interface MusicBrainzRecording {
+	id: string;
+	title: string;
+	length?: number;
+	"artist-credit"?: MusicBrainzArtistCredit[];
+}
+
+interface MusicBrainzTrack {
+	id?: string;
+	title?: string;
+	number?: string;
+	position?: number;
+	length?: number;
+	recording?: {
+		title?: string;
+		length?: number;
+	};
+}
+
+interface MusicBrainzMedium {
+	position?: number;
+	format?: string;
+	"track-count"?: number;
+	tracks?: MusicBrainzTrack[];
+}
+
+interface MusicBrainzRelease {
+	id: string;
+	title: string;
+	"track-count"?: number;
+	media?: MusicBrainzMedium[];
+}
+
+const MUSICBRAINZ_HOSTS = new Set(["musicbrainz.org", "www.musicbrainz.org"]);
+const USER_AGENT = "omp-web-fetch/1.0 (https://github.com/anthropics)";
+const MAX_TRACKS = 50;
+
+function parseEntity(url: URL): { entity: MusicBrainzEntity; mbid: string } | null {
+	if (!MUSICBRAINZ_HOSTS.has(url.hostname)) return null;
+
+	const parts = url.pathname.split("/").filter(Boolean);
+	if (parts.length < 2) return null;
+
+	const entity = parts[0] as MusicBrainzEntity;
+	if (entity !== "artist" && entity !== "release" && entity !== "recording") return null;
+
+	const mbid = parts[1];
+	if (!/^[0-9a-fA-F-]{36}$/.test(mbid)) return null;
+
+	return { entity, mbid };
+}
+
+async function fetchJson<T>(apiUrl: string, timeout: number, signal?: AbortSignal): Promise<T | null> {
+	const result = await loadPage(apiUrl, {
+		timeout,
+		signal,
+		headers: {
+			"User-Agent": USER_AGENT,
+			Accept: "application/json",
+		},
+	});
+
+	if (!result.ok) return null;
+
+	try {
+		return JSON.parse(result.content) as T;
+	} catch {
+		return null;
+	}
+}
+
+function formatLifeSpan(life: MusicBrainzLifeSpan | undefined): string | null {
+	if (!life) return null;
+
+	const begin = life.begin?.trim();
+	const end = life.end?.trim();
+
+	if (begin && end) return `${begin} - ${end}`;
+	if (begin && !end) return `${begin} - ${life.ended ? "ended" : "present"}`;
+	if (!begin && end) return `? - ${end}`;
+	if (life.ended !== undefined) return life.ended ? "ended" : "present";
+
+	return null;
+}
+
+function formatDurationMs(lengthMs: number | undefined): string | null {
+	if (!lengthMs || lengthMs <= 0) return null;
+
+	const totalSeconds = Math.round(lengthMs / 1000);
+	const hours = Math.floor(totalSeconds / 3600);
+	const minutes = Math.floor((totalSeconds % 3600) / 60);
+	const seconds = totalSeconds % 60;
+
+	if (hours > 0) {
+		return `${hours}:${minutes.toString().padStart(2, "0")}:${seconds.toString().padStart(2, "0")}`;
+	}
+
+	return `${minutes}:${seconds.toString().padStart(2, "0")}`;
+}
+
+function formatArtistCredits(credits: MusicBrainzArtistCredit[] | undefined): string | null {
+	if (!credits?.length) return null;
+
+	const names = credits
+		.map((credit) => credit.name || credit.artist?.name)
+		.filter((name): name is string => Boolean(name));
+
+	if (!names.length) return null;
+	return names.join(", ");
+}
+
+function formatTrack(track: MusicBrainzTrack): string {
+	const title = track.title || track.recording?.title || "Untitled";
+	const duration = formatDurationMs(track.length ?? track.recording?.length);
+	const number = track.number || (track.position ? String(track.position) : null);
+
+	const prefix = number ? `${number}. ` : "- ";
+	let line = `${prefix}${title}`;
+	if (duration) line += ` (${duration})`;
+	return line;
+}
+
+function buildMediumLabel(medium: MusicBrainzMedium, includePosition: boolean): string | null {
+	const parts: string[] = [];
+	if (includePosition && medium.position) parts.push(`Disc ${medium.position}`);
+	if (medium.format) parts.push(medium.format);
+	return parts.length ? parts.join(" - ") : null;
+}
+
+function buildArtistMarkdown(artist: MusicBrainzArtist): string {
+	let md = `# ${artist.name}\n\n`;
+	const meta: string[] = [];
+
+	if (artist.type) meta.push(`**Type**: ${artist.type}`);
+	if (artist.country) meta.push(`**Country**: ${artist.country}`);
+
+	const lifeSpan = formatLifeSpan(artist["life-span"]);
+	if (lifeSpan) meta.push(`**Life Span**: ${lifeSpan}`);
+
+	if (meta.length) md += `${meta.join("\n")}\n`;
+
+	return md;
+}
+
+function buildReleaseMarkdown(release: MusicBrainzRelease): string {
+	let md = `# ${release.title}\n\n`;
+
+	const media = release.media ?? [];
+	const totalTracks =
+		release["track-count"] ??
+		media.reduce((sum, medium) => sum + (medium["track-count"] ?? medium.tracks?.length ?? 0), 0);
+
+	if (totalTracks) {
+		md += `**Tracks**: ${totalTracks}\n\n`;
+	}
+
+	if (media.length) {
+		md += "## Tracks\n\n";
+		const includePosition = media.length > 1;
+
+		for (const medium of media) {
+			const label = buildMediumLabel(medium, includePosition);
+			if (label) md += `### ${label}\n\n`;
+
+			const tracks = medium.tracks ?? [];
+			if (tracks.length) {
+				const lines = tracks.slice(0, MAX_TRACKS).map(formatTrack).join("\n");
+				md += `${lines}\n\n`;
+
+				if (tracks.length > MAX_TRACKS) {
+					md += `_Showing first ${MAX_TRACKS} of ${tracks.length} tracks._\n\n`;
+				}
+			} else if (medium["track-count"]) {
+				md += `- ${medium["track-count"]} tracks (details unavailable)\n\n`;
+			}
+		}
+	}
+
+	return md;
+}
+
+function buildRecordingMarkdown(recording: MusicBrainzRecording): string {
+	let md = `# ${recording.title}\n\n`;
+	const meta: string[] = [];
+
+	const artists = formatArtistCredits(recording["artist-credit"]);
+	if (artists) meta.push(`**Artists**: ${artists}`);
+
+	const length = formatDurationMs(recording.length);
+	if (length) meta.push(`**Length**: ${length}`);
+
+	if (meta.length) md += `${meta.join("\n")}\n`;
+
+	return md;
+}
+
+export const handleMusicBrainz: SpecialHandler = async (
+	url: string,
+	timeout: number,
+	signal?: AbortSignal,
+): Promise<RenderResult | null> => {
+	try {
+		const parsed = new URL(url);
+		const parsedEntity = parseEntity(parsed);
+		if (!parsedEntity) return null;
+
+		const { entity, mbid } = parsedEntity;
+		const fetchedAt = new Date().toISOString();
+		let md = "";
+
+		if (entity === "artist") {
+			const apiUrl = `https://musicbrainz.org/ws/2/artist/${mbid}?fmt=json&inc=url-rels`;
+			const artist = await fetchJson<MusicBrainzArtist>(apiUrl, timeout, signal);
+			if (!artist) return null;
+			md = buildArtistMarkdown(artist);
+		} else if (entity === "release") {
+			const apiUrl = `https://musicbrainz.org/ws/2/release/${mbid}?fmt=json&inc=recordings`;
+			const release = await fetchJson<MusicBrainzRelease>(apiUrl, timeout, signal);
+			if (!release) return null;
+			md = buildReleaseMarkdown(release);
+		} else {
+			const apiUrl = `https://musicbrainz.org/ws/2/recording/${mbid}?fmt=json`;
+			const recording = await fetchJson<MusicBrainzRecording>(apiUrl, timeout, signal);
+			if (!recording) return null;
+			md = buildRecordingMarkdown(recording);
+		}
+
+		const output = finalizeOutput(md);
+		return {
+			url,
+			finalUrl: url,
+			contentType: "text/markdown",
+			method: "musicbrainz-api",
+			content: output.content,
+			fetchedAt,
+			truncated: output.truncated,
+			notes: ["Fetched via MusicBrainz API"],
+		};
+	} catch {}
+
+	return null;
+};

package/src/core/tools/web-scrapers/npm.ts

@@ -0,0 +1,114 @@
+import type { RenderResult, SpecialHandler } from "./types";
+import { finalizeOutput, formatCount, loadPage } from "./types";
+
+/**
+ * Handle npm URLs via registry API
+ */
+export const handleNpm: SpecialHandler = async (
+	url: string,
+	timeout: number,
+	signal?: AbortSignal,
+): Promise<RenderResult | null> => {
+	try {
+		const parsed = new URL(url);
+		if (parsed.hostname !== "www.npmjs.com" && parsed.hostname !== "npmjs.com") return null;
+
+		// Extract package name from /package/[scope/]name
+		const match = parsed.pathname.match(/^\/package\/(.+?)(?:\/|$)/);
+		if (!match) return null;
+
+		let packageName = decodeURIComponent(match[1]);
+		// Handle scoped packages: /package/@scope/name
+		if (packageName.startsWith("@")) {
+			const scopeMatch = parsed.pathname.match(/^\/package\/(@[^/]+\/[^/]+)/);
+			if (scopeMatch) packageName = decodeURIComponent(scopeMatch[1]);
+		}
+
+		const fetchedAt = new Date().toISOString();
+
+		// Fetch from npm registry - use /latest endpoint for smaller response
+		const latestUrl = `https://registry.npmjs.org/${packageName}/latest`;
+		const downloadsUrl = `https://api.npmjs.org/downloads/point/last-week/${encodeURIComponent(packageName)}`;
+
+		// Fetch package info and download stats in parallel
+		const [result, downloadsResult] = await Promise.all([
+			loadPage(latestUrl, { timeout, signal }),
+			loadPage(downloadsUrl, { timeout: Math.min(timeout, 5), signal }),
+		]);
+
+		if (!result.ok) return null;
+
+		// Parse download stats
+		let weeklyDownloads: number | null = null;
+		if (downloadsResult.ok) {
+			try {
+				const dlData = JSON.parse(downloadsResult.content) as { downloads?: number };
+				weeklyDownloads = dlData.downloads ?? null;
+			} catch {}
+		}
+
+		let pkg: {
+			name: string;
+			version: string;
+			description?: string;
+			license?: string | { type: string };
+			homepage?: string;
+			repository?: { url: string } | string;
+			keywords?: string[];
+			maintainers?: Array<{ name: string }>;
+			dependencies?: Record<string, string>;
+			readme?: string;
+		};
+
+		try {
+			pkg = JSON.parse(result.content);
+		} catch {
+			return null; // JSON parse failed (truncated response)
+		}
+
+		let md = `# ${pkg.name}\n\n`;
+		if (pkg.description) md += `${pkg.description}\n\n`;
+
+		md += `**Latest:** ${pkg.version || "unknown"}`;
+		if (pkg.license) {
+			const license = typeof pkg.license === "string" ? pkg.license : (pkg.license.type ?? String(pkg.license));
+			md += ` · **License:** ${license}`;
+		}
+		md += "\n";
+		if (weeklyDownloads !== null) {
+			md += `**Weekly Downloads:** ${formatCount(weeklyDownloads)}\n`;
+		}
+		md += "\n";
+
+		if (pkg.homepage) md += `**Homepage:** ${pkg.homepage}\n`;
+		const repoUrl = typeof pkg.repository === "string" ? pkg.repository : pkg.repository?.url;
+		if (repoUrl) md += `**Repository:** ${repoUrl.replace(/^git\+/, "").replace(/\.git$/, "")}\n`;
+		if (pkg.keywords?.length) md += `**Keywords:** ${pkg.keywords.join(", ")}\n`;
+		if (pkg.maintainers?.length) md += `**Maintainers:** ${pkg.maintainers.map((m) => m.name).join(", ")}\n`;
+
+		if (pkg.dependencies && Object.keys(pkg.dependencies).length > 0) {
+			md += `\n## Dependencies\n\n`;
+			for (const [dep, version] of Object.entries(pkg.dependencies)) {
+				md += `- ${dep}: ${version}\n`;
+			}
+		}
+
+		if (pkg.readme) {
+			md += `\n---\n\n## README\n\n${pkg.readme}\n`;
+		}
+
+		const output = finalizeOutput(md);
+		return {
+			url,
+			finalUrl: url,
+			contentType: "text/markdown",
+			method: "npm",
+			content: output.content,
+			fetchedAt,
+			truncated: output.truncated,
+			notes: ["Fetched via npm registry"],
+		};
+	} catch {}
+
+	return null;
+};

package/src/core/tools/web-scrapers/nuget.ts

@@ -0,0 +1,205 @@
+import type { RenderResult, SpecialHandler } from "./types";
+import { finalizeOutput, formatCount, loadPage } from "./types";
+
+interface NuGetCatalogEntry {
+	id: string;
+	version: string;
+	description?: string;
+	authors?: string;
+	projectUrl?: string;
+	licenseUrl?: string;
+	licenseExpression?: string;
+	tags?: string[];
+	dependencyGroups?: Array<{
+		targetFramework?: string;
+		dependencies?: Array<{
+			id: string;
+			range: string;
+		}>;
+	}>;
+	published?: string;
+}
+
+interface NuGetRegistrationItem {
+	catalogEntry: NuGetCatalogEntry;
+	packageContent?: string;
+}
+
+interface NuGetRegistrationPage {
+	items?: NuGetRegistrationItem[];
+	"@id"?: string;
+}
+
+interface NuGetRegistrationIndex {
+	items: NuGetRegistrationPage[];
+}
+
+/**
+ * Handle NuGet URLs via API
+ */
+export const handleNuGet: SpecialHandler = async (
+	url: string,
+	timeout: number,
+	signal?: AbortSignal,
+): Promise<RenderResult | null> => {
+	try {
+		const parsed = new URL(url);
+		if (parsed.hostname !== "www.nuget.org" && parsed.hostname !== "nuget.org") return null;
+
+		// Extract package name and optional version from /packages/name or /packages/name/version
+		const match = parsed.pathname.match(/^\/packages\/([^/]+)(?:\/([^/]+))?/i);
+		if (!match) return null;
+
+		const packageName = decodeURIComponent(match[1]);
+		const requestedVersion = match[2] ? decodeURIComponent(match[2]) : null;
+		const fetchedAt = new Date().toISOString();
+
+		// Fetch from NuGet registration API (package name must be lowercase)
+		const apiUrl = `https://api.nuget.org/v3/registration5-gz-semver2/${packageName.toLowerCase()}/index.json`;
+		const result = await loadPage(apiUrl, { timeout, signal });
+
+		if (!result.ok) return null;
+
+		let index: NuGetRegistrationIndex;
+		try {
+			index = JSON.parse(result.content);
+		} catch {
+			return null;
+		}
+
+		if (!index.items?.length) return null;
+
+		// Get the latest page (or fetch it if not inlined)
+		let latestPage = index.items[index.items.length - 1];
+
+		// If items are not inlined, fetch the page
+		if (!latestPage.items && latestPage["@id"]) {
+			const pageResult = await loadPage(latestPage["@id"], { timeout, signal });
+			if (!pageResult.ok) return null;
+			try {
+				latestPage = JSON.parse(pageResult.content);
+			} catch {
+				return null;
+			}
+		}
+
+		if (!latestPage.items?.length) return null;
+
+		// Find the requested version or get the latest
+		let targetEntry: NuGetCatalogEntry | null = null;
+
+		if (requestedVersion) {
+			// Search all pages for the requested version
+			for (const page of index.items) {
+				let pageItems = page.items;
+
+				// Fetch page if items not inlined
+				if (!pageItems && page["@id"]) {
+					const pageResult = await loadPage(page["@id"], { timeout: Math.min(timeout, 5), signal });
+					if (pageResult.ok) {
+						try {
+							const fetchedPage = JSON.parse(pageResult.content) as NuGetRegistrationPage;
+							pageItems = fetchedPage.items;
+						} catch {}
+					}
+				}
+
+				if (pageItems) {
+					const found = pageItems.find(
+						(item) => item.catalogEntry.version.toLowerCase() === requestedVersion.toLowerCase(),
+					);
+					if (found) {
+						targetEntry = found.catalogEntry;
+						break;
+					}
+				}
+			}
+		}
+
+		// If no specific version requested or not found, use the latest
+		if (!targetEntry) {
+			const latestItem = latestPage.items[latestPage.items.length - 1];
+			targetEntry = latestItem.catalogEntry;
+		}
+
+		// Fetch download stats via search API
+		let totalDownloads: number | null = null;
+		const searchUrl = `https://api.nuget.org/v3/query?q=packageid:${encodeURIComponent(packageName)}&prerelease=true&take=1`;
+		const searchResult = await loadPage(searchUrl, { timeout: Math.min(timeout, 5), signal });
+
+		if (searchResult.ok) {
+			try {
+				const searchData = JSON.parse(searchResult.content) as {
+					data?: Array<{ totalDownloads?: number }>;
+				};
+				totalDownloads = searchData.data?.[0]?.totalDownloads ?? null;
+			} catch {}
+		}
+
+		// Format markdown output
+		let md = `# ${targetEntry.id}\n\n`;
+		if (targetEntry.description) md += `${targetEntry.description}\n\n`;
+
+		md += `**Version:** ${targetEntry.version}`;
+		if (targetEntry.licenseExpression) {
+			md += ` · **License:** ${targetEntry.licenseExpression}`;
+		} else if (targetEntry.licenseUrl) {
+			md += ` · **License:** [View](${targetEntry.licenseUrl})`;
+		}
+		md += "\n";
+
+		if (totalDownloads !== null) {
+			md += `**Total Downloads:** ${formatCount(totalDownloads)}\n`;
+		}
+
+		if (targetEntry.authors) md += `**Authors:** ${targetEntry.authors}\n`;
+		if (targetEntry.projectUrl) md += `**Project URL:** ${targetEntry.projectUrl}\n`;
+		if (targetEntry.tags?.length) md += `**Tags:** ${targetEntry.tags.join(", ")}\n`;
+		if (targetEntry.published) {
+			const pubDate = targetEntry.published.split("T")[0];
+			md += `**Published:** ${pubDate}\n`;
+		}
+
+		// Show dependencies by target framework
+		if (targetEntry.dependencyGroups?.length) {
+			const hasAnyDeps = targetEntry.dependencyGroups.some((g) => g.dependencies?.length);
+			if (hasAnyDeps) {
+				md += `\n## Dependencies\n\n`;
+				for (const group of targetEntry.dependencyGroups) {
+					if (!group.dependencies?.length) continue;
+					const framework = group.targetFramework || "All Frameworks";
+					md += `### ${framework}\n\n`;
+					for (const dep of group.dependencies) {
+						md += `- ${dep.id} (${dep.range})\n`;
+					}
+					md += "\n";
+				}
+			}
+		}
+
+		// Show recent versions from the latest page
+		if (latestPage.items && latestPage.items.length > 1) {
+			md += `## Recent Versions\n\n`;
+			const recentVersions = latestPage.items.slice(-5).reverse();
+			for (const item of recentVersions) {
+				const entry = item.catalogEntry;
+				const pubDate = entry.published?.split("T")[0] || "unknown";
+				md += `- **${entry.version}** (${pubDate})\n`;
+			}
+		}
+
+		const output = finalizeOutput(md);
+		return {
+			url,
+			finalUrl: url,
+			contentType: "text/markdown",
+			method: "nuget",
+			content: output.content,
+			fetchedAt,
+			truncated: output.truncated,
+			notes: ["Fetched via NuGet API"],
+		};
+	} catch {}
+
+	return null;
+};