skilld 1.7.3 → 1.7.4

package/dist/_chunks/sources.mjs

@@ -1,11 +1,11 @@
-import { t as getCacheDir } from "./version.mjs";
-import { i as readPackageJsonSafe } from "./package-json.mjs";
 import { t as yamlEscape } from "./yaml.mjs";
+import { i as readPackageJsonSafe } from "./package-json.mjs";
+import { t as getCacheDir } from "./version.mjs";
 import { i as parseFrontmatter, n as extractLinks, r as extractTitle, t as extractDescription } from "./markdown.mjs";
-import { c as getBlogPreset, l as getCrawlUrl, r as mapInsert, u as getDocOverride } from "./shared.mjs";
+import { n as getCrawlUrl, r as getDocOverride, t as getBlogPreset } from "./package-registry.mjs";
+import { createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "pathe";
-import { createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from "node:fs";
 import { htmlToMarkdown } from "mdream";
 import pLimit from "p-limit";
 import { spawnSync } from "node:child_process";
@@ -79,6 +79,15 @@ function markRepoPrivate(owner, repo) {
 function isKnownPrivateRepo(owner, repo) {
 	return _needsAuth.has(`${owner}/${repo}`);
 }
+async function fetchUnghOrApi(owner, repo, ungh, api) {
+	if (!isKnownPrivateRepo(owner, repo)) {
+		const r = await ungh().catch(() => null);
+		if (r) return r;
+	}
+	const r = await api();
+	if (r) markRepoPrivate(owner, repo);
+	return r;
+}
 const GH_API = "https://api.github.com";
 const ghApiFetch = ofetch.create({
 	retry: 2,
@@ -499,6 +508,261 @@ async function fetchBlogReleases(packageName, installedVersion) {
 		content: formatBlogRelease(r)
 	}));
 }
+function mapInsert(map, key, create) {
+	let val = map.get(key);
+	if (val === void 0) {
+		val = create();
+		map.set(key, val);
+	}
+	return val;
+}
+async function listFilesAtRef(owner, repo, ref) {
+	return await fetchUnghOrApi(owner, repo, async () => {
+		const data = await $fetch(`https://ungh.cc/repos/${owner}/${repo}/files/${ref}`);
+		return data.files?.length ? data.files.map((f) => f.path) : null;
+	}, async () => {
+		const tree = await ghApi(`repos/${owner}/${repo}/git/trees/${ref}?recursive=1`);
+		return tree?.tree?.length ? tree.tree.map((f) => f.path) : null;
+	}) ?? [];
+}
+async function findGitTag(owner, repo, version, packageName, branchHint) {
+	const candidates = [`v${version}`, version];
+	if (packageName) candidates.push(`${packageName}@${version}`);
+	for (const tag of candidates) {
+		const files = await listFilesAtRef(owner, repo, tag);
+		if (files.length > 0) return {
+			ref: tag,
+			files
+		};
+	}
+	if (packageName) {
+		const latestTag = await findLatestReleaseTag(owner, repo, packageName);
+		if (latestTag) {
+			const files = await listFilesAtRef(owner, repo, latestTag);
+			if (files.length > 0) return {
+				ref: latestTag,
+				files
+			};
+		}
+	}
+	const branches = branchHint ? [branchHint, ...["main", "master"].filter((b) => b !== branchHint)] : ["main", "master"];
+	for (const branch of branches) {
+		const files = await listFilesAtRef(owner, repo, branch);
+		if (files.length > 0) return {
+			ref: branch,
+			files,
+			fallback: true
+		};
+	}
+	return null;
+}
+async function fetchUnghReleases(owner, repo) {
+	return await fetchUnghOrApi(owner, repo, async () => {
+		const data = await $fetch(`https://ungh.cc/repos/${owner}/${repo}/releases`);
+		return data.releases?.length ? data.releases : null;
+	}, async () => {
+		const raw = await ghApiPaginated(`repos/${owner}/${repo}/releases`);
+		return raw.length > 0 ? raw.map((r) => ({
+			tag: r.tag_name,
+			publishedAt: r.published_at
+		})) : null;
+	}) ?? [];
+}
+async function findLatestReleaseTag(owner, repo, packageName) {
+	const prefix = `${packageName}@`;
+	return (await fetchUnghReleases(owner, repo)).find((r) => r.tag.startsWith(prefix))?.tag ?? null;
+}
+const MIN_GIT_DOCS = 5;
+const isShallowGitDocs = (n) => n > 0 && n < 5;
+function filterDocFiles(files, pathPrefix) {
+	return files.filter((f) => f.startsWith(pathPrefix) && /\.(?:md|mdx)$/.test(f));
+}
+const FRAMEWORK_NAMES = new Set([
+	"vue",
+	"react",
+	"solid",
+	"angular",
+	"svelte",
+	"preact",
+	"lit",
+	"qwik"
+]);
+function filterFrameworkDocs(files, packageName) {
+	if (!packageName) return files;
+	const shortName = packageName.replace(/^@.*\//, "");
+	const targetFramework = [...FRAMEWORK_NAMES].find((fw) => shortName.includes(fw));
+	if (!targetFramework) return files;
+	const otherFrameworks = [...FRAMEWORK_NAMES].filter((fw) => fw !== targetFramework);
+	const excludePattern = new RegExp(`\\b(?:${otherFrameworks.join("|")})\\b`);
+	return files.filter((f) => !excludePattern.test(f));
+}
+const NOISE_PATTERNS = [
+	/^\.changeset\//,
+	/CHANGELOG\.md$/i,
+	/CONTRIBUTING\.md$/i,
+	/^\.github\//
+];
+const EXCLUDE_DIRS = new Set([
+	"test",
+	"tests",
+	"__tests__",
+	"fixtures",
+	"fixture",
+	"examples",
+	"example",
+	"node_modules",
+	".git",
+	"dist",
+	"build",
+	"coverage",
+	"e2e",
+	"spec",
+	"mocks",
+	"__mocks__"
+]);
+const DOC_DIR_BONUS = new Set([
+	"docs",
+	"documentation",
+	"pages",
+	"content",
+	"website",
+	"guide",
+	"guides",
+	"wiki",
+	"manual",
+	"api"
+]);
+function hasExcludedDir(path) {
+	return path.split("/").some((p) => EXCLUDE_DIRS.has(p.toLowerCase()));
+}
+function getPathDepth(path) {
+	return path.split("/").filter(Boolean).length;
+}
+function hasDocDirBonus(path) {
+	return path.split("/").some((p) => DOC_DIR_BONUS.has(p.toLowerCase()));
+}
+function scoreDocDir(dir, fileCount) {
+	const depth = getPathDepth(dir) || 1;
+	return fileCount * (hasDocDirBonus(dir) ? 1.5 : 1) / depth;
+}
+function discoverDocFiles(allFiles, packageName) {
+	const mdFiles = allFiles.filter((f) => /\.(?:md|mdx)$/.test(f)).filter((f) => !NOISE_PATTERNS.some((p) => p.test(f))).filter((f) => f.includes("/"));
+	if (packageName?.includes("/")) {
+		const subPkgPrefix = `packages/${packageName.split("/").pop().toLowerCase()}/`;
+		const subPkgFiles = mdFiles.filter((f) => f.startsWith(subPkgPrefix));
+		if (subPkgFiles.length >= 3) return {
+			files: subPkgFiles,
+			prefix: subPkgPrefix
+		};
+	}
+	const docsGroups = /* @__PURE__ */ new Map();
+	for (const file of mdFiles) {
+		const docsIdx = file.lastIndexOf("/docs/");
+		if (docsIdx === -1) continue;
+		mapInsert(docsGroups, file.slice(0, docsIdx + 6), () => []).push(file);
+	}
+	if (docsGroups.size > 0) {
+		const largest = [...docsGroups.entries()].sort((a, b) => b[1].length - a[1].length)[0];
+		if (largest[1].length >= 3) {
+			const fullPrefix = largest[0];
+			const docsIdx = fullPrefix.lastIndexOf("docs/");
+			const stripPrefix = docsIdx > 0 ? fullPrefix.slice(0, docsIdx) : "";
+			return {
+				files: largest[1],
+				prefix: stripPrefix
+			};
+		}
+	}
+	const dirGroups = /* @__PURE__ */ new Map();
+	for (const file of mdFiles) {
+		if (hasExcludedDir(file)) continue;
+		const lastSlash = file.lastIndexOf("/");
+		if (lastSlash === -1) continue;
+		mapInsert(dirGroups, file.slice(0, lastSlash + 1), () => []).push(file);
+	}
+	if (dirGroups.size === 0) return null;
+	const scored = Array.from(dirGroups.entries(), ([dir, files]) => ({
+		dir,
+		files,
+		score: scoreDocDir(dir, files.length)
+	})).filter((d) => d.files.length >= 5).sort((a, b) => b.score - a.score);
+	if (scored.length === 0) return null;
+	const best = scored[0];
+	return {
+		files: best.files,
+		prefix: best.dir
+	};
+}
+async function listDocsAtRef(owner, repo, ref, pathPrefix = "docs/") {
+	return filterDocFiles(await listFilesAtRef(owner, repo, ref), pathPrefix);
+}
+async function fetchGitDocs(owner, repo, version, packageName, repoUrl) {
+	const override = packageName ? getDocOverride(packageName) : void 0;
+	if (override) {
+		const ref = override.ref || "main";
+		const fallback = !override.ref;
+		const files = await listDocsAtRef(override.owner, override.repo, ref, `${override.path}/`);
+		if (files.length === 0) return null;
+		return {
+			baseUrl: `https://raw.githubusercontent.com/${override.owner}/${override.repo}/${ref}`,
+			ref,
+			files,
+			fallback,
+			docsPrefix: `${override.path}/` !== "docs/" ? `${override.path}/` : void 0
+		};
+	}
+	const tag = await findGitTag(owner, repo, version, packageName, repoUrl ? extractBranchHint(repoUrl) : void 0);
+	if (!tag) return null;
+	let docs = filterDocFiles(tag.files, "docs/");
+	let docsPrefix;
+	let allFiles;
+	if (docs.length === 0) {
+		const discovered = discoverDocFiles(tag.files, packageName);
+		if (discovered) {
+			docs = discovered.files;
+			docsPrefix = discovered.prefix || void 0;
+			allFiles = tag.files;
+		}
+	}
+	docs = filterFrameworkDocs(docs, packageName);
+	if (docs.length === 0) return null;
+	return {
+		baseUrl: `https://raw.githubusercontent.com/${owner}/${repo}/${tag.ref}`,
+		ref: tag.ref,
+		files: docs,
+		docsPrefix,
+		allFiles,
+		fallback: tag.fallback
+	};
+}
+function normalizePath(p) {
+	return p.replace(/^\//, "").replace(/\.(?:md|mdx)$/, "");
+}
+function validateGitDocsWithLlms(llmsLinks, repoFiles) {
+	if (llmsLinks.length === 0) return {
+		isValid: true,
+		matchRatio: 1
+	};
+	const sample = llmsLinks.slice(0, 10);
+	const normalizedLinks = sample.map((link) => {
+		let path = link.url;
+		if (path.startsWith("http")) try {
+			path = new URL(path).pathname;
+		} catch {}
+		return normalizePath(path);
+	});
+	const repoNormalized = new Set(repoFiles.map(normalizePath));
+	let matches = 0;
+	for (const linkPath of normalizedLinks) for (const repoPath of repoNormalized) if (repoPath === linkPath || repoPath.endsWith(`/${linkPath}`)) {
+		matches++;
+		break;
+	}
+	const matchRatio = matches / sample.length;
+	return {
+		isValid: matchRatio >= .3,
+		matchRatio
+	};
+}
 let _ghAvailable;
 function isGhAvailable() {
 	if (_ghAvailable !== void 0) return _ghAvailable;
@@ -762,385 +1026,132 @@ function formatIssueAsMarkdown(issue) {
 		`# ${issue.title}`
 	];
 	if (issue.body) {
-		const body = truncateBody(issue.body, limit);
-		lines.push("", body);
-	}
-	if (issue.topComments.length > 0) {
-		lines.push("", "---", "", "## Top Comments");
-		for (const c of issue.topComments) {
-			const reactions = c.reactions > 0 ? ` (+${c.reactions})` : "";
-			const maintainer = c.isMaintainer ? " [maintainer]" : "";
-			const commentBody = truncateBody(c.body, 600);
-			lines.push("", `**@${c.author}**${maintainer}${reactions}:`, "", commentBody);
-		}
-	}
-	return lines.join("\n");
-}
-function generateIssueIndex(issues) {
-	const byType = /* @__PURE__ */ new Map();
-	for (const issue of issues) mapInsert(byType, issue.type, () => []).push(issue);
-	const typeLabels = {
-		bug: "Bugs & Regressions",
-		question: "Questions & Usage Help",
-		docs: "Documentation",
-		feature: "Feature Requests",
-		other: "Other"
-	};
-	const typeOrder = [
-		"bug",
-		"question",
-		"docs",
-		"other",
-		"feature"
-	];
-	const sections = [
-		[
-			"---",
-			`total: ${issues.length}`,
-			`open: ${issues.filter((i) => i.state === "open").length}`,
-			`closed: ${issues.filter((i) => i.state !== "open").length}`,
-			"---"
-		].join("\n"),
-		"",
-		"# Issues Index",
-		""
-	];
-	for (const type of typeOrder) {
-		const group = byType.get(type);
-		if (!group?.length) continue;
-		sections.push(`## ${typeLabels[type]} (${group.length})`, "");
-		for (const issue of group) {
-			const reactions = issue.reactions > 0 ? ` (+${issue.reactions})` : "";
-			const state = issue.state === "open" ? "" : " [closed]";
-			const resolved = issue.resolvedIn ? ` [fixed in ${issue.resolvedIn}]` : "";
-			const date = isoDate(issue.createdAt);
-			sections.push(`- [#${issue.number}](./issue-${issue.number}.md): ${issue.title}${reactions}${state}${resolved} (${date})`);
-		}
-		sections.push("");
-	}
-	return sections.join("\n");
-}
-async function fetchLlmsUrl(docsUrl) {
-	const llmsUrl = `${new URL(docsUrl).origin}/llms.txt`;
-	if (await verifyUrl(llmsUrl)) return llmsUrl;
-	return null;
-}
-async function fetchLlmsTxt(url) {
-	const content = await fetchText(url);
-	if (!content || content.length < 50) return null;
-	return {
-		raw: content,
-		links: parseMarkdownLinks(content)
-	};
-}
-function parseMarkdownLinks(content) {
-	return extractLinks(content).filter((l) => l.url.endsWith(".md"));
-}
-function isSafeUrl(url) {
-	try {
-		const parsed = new URL(url);
-		if (parsed.protocol !== "https:") return false;
-		const host = parsed.hostname;
-		if (host === "localhost" || host === "0.0.0.0" || host === "[::1]") return false;
-		if (/^(?:127\.|10\.|172\.(?:1[6-9]|2\d|3[01])\.|192\.168\.|169\.254\.)/.test(host)) return false;
-		if (/^\[(?:f[cd]|fe[89ab]|::ffff:)/i.test(host)) return false;
-		return true;
-	} catch {
-		return false;
-	}
-}
-async function downloadLlmsDocs(llmsContent, baseUrl, onProgress) {
-	const limit = pLimit(5);
-	let completed = 0;
-	return (await Promise.all(llmsContent.links.map((link) => limit(async () => {
-		const url = link.url.startsWith("http") ? link.url : `${baseUrl.replace(/\/$/, "")}${link.url.startsWith("/") ? "" : "/"}${link.url}`;
-		if (!isSafeUrl(url)) return null;
-		const content = await fetchText(url);
-		onProgress?.(link.url, ++completed, llmsContent.links.length);
-		if (content && content.length > 100) return {
-			url: link.url.startsWith("http") ? new URL(link.url).pathname : link.url,
-			title: link.title,
-			content
-		};
-		return null;
-	})))).filter((d) => d !== null);
-}
-function normalizeLlmsLinks(content, baseUrl) {
-	let normalized = content;
-	if (baseUrl) {
-		const escaped = baseUrl.replace(/\/$/, "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-		normalized = normalized.replace(new RegExp(`\\]\\(${escaped}(/[^)]+\\.md)\\)`, "g"), "](./docs$1)");
-	}
-	normalized = normalized.replace(/\]\(\/([^)]+\.md)\)/g, "](./docs/$1)");
-	return normalized;
-}
-function extractSections(content, patterns) {
-	const sections = [];
-	const parts = content.split(/\n---\n/);
-	for (const part of parts) {
-		const urlMatch = part.match(/^url: *(\S.*)$/m);
-		if (!urlMatch) continue;
-		const url = urlMatch[1];
-		if (patterns.some((p) => url.includes(p))) {
-			const contentStart = part.indexOf("\n", part.indexOf("url:"));
-			if (contentStart > -1) sections.push(part.slice(contentStart + 1));
-		}
-	}
-	if (sections.length === 0) return null;
-	return sections.join("\n\n---\n\n");
-}
-const MIN_GIT_DOCS = 5;
-const isShallowGitDocs = (n) => n > 0 && n < 5;
-async function listFilesAtRef(owner, repo, ref) {
-	if (!isKnownPrivateRepo(owner, repo)) {
-		const data = await $fetch(`https://ungh.cc/repos/${owner}/${repo}/files/${ref}`).catch(() => null);
-		if (data?.files?.length) return data.files.map((f) => f.path);
-	}
-	const tree = await ghApi(`repos/${owner}/${repo}/git/trees/${ref}?recursive=1`);
-	if (tree?.tree?.length) {
-		markRepoPrivate(owner, repo);
-		return tree.tree.map((f) => f.path);
-	}
-	return [];
-}
-async function findGitTag(owner, repo, version, packageName, branchHint) {
-	const candidates = [`v${version}`, version];
-	if (packageName) candidates.push(`${packageName}@${version}`);
-	for (const tag of candidates) {
-		const files = await listFilesAtRef(owner, repo, tag);
-		if (files.length > 0) return {
-			ref: tag,
-			files
-		};
-	}
-	if (packageName) {
-		const latestTag = await findLatestReleaseTag(owner, repo, packageName);
-		if (latestTag) {
-			const files = await listFilesAtRef(owner, repo, latestTag);
-			if (files.length > 0) return {
-				ref: latestTag,
-				files
-			};
-		}
-	}
-	const branches = branchHint ? [branchHint, ...["main", "master"].filter((b) => b !== branchHint)] : ["main", "master"];
-	for (const branch of branches) {
-		const files = await listFilesAtRef(owner, repo, branch);
-		if (files.length > 0) return {
-			ref: branch,
-			files,
-			fallback: true
-		};
-	}
-	return null;
-}
-async function fetchUnghReleases(owner, repo) {
-	if (!isKnownPrivateRepo(owner, repo)) {
-		const data = await $fetch(`https://ungh.cc/repos/${owner}/${repo}/releases`).catch(() => null);
-		if (data?.releases?.length) return data.releases;
-	}
-	const raw = await ghApiPaginated(`repos/${owner}/${repo}/releases`);
-	if (raw.length > 0) {
-		markRepoPrivate(owner, repo);
-		return raw.map((r) => ({
-			tag: r.tag_name,
-			publishedAt: r.published_at
-		}));
-	}
-	return [];
-}
-async function findLatestReleaseTag(owner, repo, packageName) {
-	const prefix = `${packageName}@`;
-	return (await fetchUnghReleases(owner, repo)).find((r) => r.tag.startsWith(prefix))?.tag ?? null;
-}
-function filterDocFiles(files, pathPrefix) {
-	return files.filter((f) => f.startsWith(pathPrefix) && /\.(?:md|mdx)$/.test(f));
-}
-const FRAMEWORK_NAMES = new Set([
-	"vue",
-	"react",
-	"solid",
-	"angular",
-	"svelte",
-	"preact",
-	"lit",
-	"qwik"
-]);
-function filterFrameworkDocs(files, packageName) {
-	if (!packageName) return files;
-	const shortName = packageName.replace(/^@.*\//, "");
-	const targetFramework = [...FRAMEWORK_NAMES].find((fw) => shortName.includes(fw));
-	if (!targetFramework) return files;
-	const otherFrameworks = [...FRAMEWORK_NAMES].filter((fw) => fw !== targetFramework);
-	const excludePattern = new RegExp(`\\b(?:${otherFrameworks.join("|")})\\b`);
-	return files.filter((f) => !excludePattern.test(f));
-}
-const NOISE_PATTERNS = [
-	/^\.changeset\//,
-	/CHANGELOG\.md$/i,
-	/CONTRIBUTING\.md$/i,
-	/^\.github\//
-];
-const EXCLUDE_DIRS = new Set([
-	"test",
-	"tests",
-	"__tests__",
-	"fixtures",
-	"fixture",
-	"examples",
-	"example",
-	"node_modules",
-	".git",
-	"dist",
-	"build",
-	"coverage",
-	"e2e",
-	"spec",
-	"mocks",
-	"__mocks__"
-]);
-const DOC_DIR_BONUS = new Set([
-	"docs",
-	"documentation",
-	"pages",
-	"content",
-	"website",
-	"guide",
-	"guides",
-	"wiki",
-	"manual",
-	"api"
-]);
-function hasExcludedDir(path) {
-	return path.split("/").some((p) => EXCLUDE_DIRS.has(p.toLowerCase()));
-}
-function getPathDepth(path) {
-	return path.split("/").filter(Boolean).length;
-}
-function hasDocDirBonus(path) {
-	return path.split("/").some((p) => DOC_DIR_BONUS.has(p.toLowerCase()));
-}
-function scoreDocDir(dir, fileCount) {
-	const depth = getPathDepth(dir) || 1;
-	return fileCount * (hasDocDirBonus(dir) ? 1.5 : 1) / depth;
-}
-function discoverDocFiles(allFiles, packageName) {
-	const mdFiles = allFiles.filter((f) => /\.(?:md|mdx)$/.test(f)).filter((f) => !NOISE_PATTERNS.some((p) => p.test(f))).filter((f) => f.includes("/"));
-	if (packageName?.includes("/")) {
-		const subPkgPrefix = `packages/${packageName.split("/").pop().toLowerCase()}/`;
-		const subPkgFiles = mdFiles.filter((f) => f.startsWith(subPkgPrefix));
-		if (subPkgFiles.length >= 3) return {
-			files: subPkgFiles,
-			prefix: subPkgPrefix
-		};
-	}
-	const docsGroups = /* @__PURE__ */ new Map();
-	for (const file of mdFiles) {
-		const docsIdx = file.lastIndexOf("/docs/");
-		if (docsIdx === -1) continue;
-		mapInsert(docsGroups, file.slice(0, docsIdx + 6), () => []).push(file);
+		const body = truncateBody(issue.body, limit);
+		lines.push("", body);
 	}
-	if (docsGroups.size > 0) {
-		const largest = [...docsGroups.entries()].sort((a, b) => b[1].length - a[1].length)[0];
-		if (largest[1].length >= 3) {
-			const fullPrefix = largest[0];
-			const docsIdx = fullPrefix.lastIndexOf("docs/");
-			const stripPrefix = docsIdx > 0 ? fullPrefix.slice(0, docsIdx) : "";
-			return {
-				files: largest[1],
-				prefix: stripPrefix
-			};
+	if (issue.topComments.length > 0) {
+		lines.push("", "---", "", "## Top Comments");
+		for (const c of issue.topComments) {
+			const reactions = c.reactions > 0 ? ` (+${c.reactions})` : "";
+			const maintainer = c.isMaintainer ? " [maintainer]" : "";
+			const commentBody = truncateBody(c.body, 600);
+			lines.push("", `**@${c.author}**${maintainer}${reactions}:`, "", commentBody);
 		}
 	}
-	const dirGroups = /* @__PURE__ */ new Map();
-	for (const file of mdFiles) {
-		if (hasExcludedDir(file)) continue;
-		const lastSlash = file.lastIndexOf("/");
-		if (lastSlash === -1) continue;
-		mapInsert(dirGroups, file.slice(0, lastSlash + 1), () => []).push(file);
+	return lines.join("\n");
+}
+function generateIssueIndex(issues) {
+	const byType = /* @__PURE__ */ new Map();
+	for (const issue of issues) mapInsert(byType, issue.type, () => []).push(issue);
+	const typeLabels = {
+		bug: "Bugs & Regressions",
+		question: "Questions & Usage Help",
+		docs: "Documentation",
+		feature: "Feature Requests",
+		other: "Other"
+	};
+	const typeOrder = [
+		"bug",
+		"question",
+		"docs",
+		"other",
+		"feature"
+	];
+	const sections = [
+		[
+			"---",
+			`total: ${issues.length}`,
+			`open: ${issues.filter((i) => i.state === "open").length}`,
+			`closed: ${issues.filter((i) => i.state !== "open").length}`,
+			"---"
+		].join("\n"),
+		"",
+		"# Issues Index",
+		""
+	];
+	for (const type of typeOrder) {
+		const group = byType.get(type);
+		if (!group?.length) continue;
+		sections.push(`## ${typeLabels[type]} (${group.length})`, "");
+		for (const issue of group) {
+			const reactions = issue.reactions > 0 ? ` (+${issue.reactions})` : "";
+			const state = issue.state === "open" ? "" : " [closed]";
+			const resolved = issue.resolvedIn ? ` [fixed in ${issue.resolvedIn}]` : "";
+			const date = isoDate(issue.createdAt);
+			sections.push(`- [#${issue.number}](./issue-${issue.number}.md): ${issue.title}${reactions}${state}${resolved} (${date})`);
+		}
+		sections.push("");
 	}
-	if (dirGroups.size === 0) return null;
-	const scored = Array.from(dirGroups.entries(), ([dir, files]) => ({
-		dir,
-		files,
-		score: scoreDocDir(dir, files.length)
-	})).filter((d) => d.files.length >= 5).sort((a, b) => b.score - a.score);
-	if (scored.length === 0) return null;
-	const best = scored[0];
+	return sections.join("\n");
+}
+async function fetchLlmsUrl(docsUrl) {
+	const llmsUrl = `${new URL(docsUrl).origin}/llms.txt`;
+	if (await verifyUrl(llmsUrl)) return llmsUrl;
+	return null;
+}
+async function fetchLlmsTxt(url) {
+	const content = await fetchText(url);
+	if (!content || content.length < 50) return null;
 	return {
-		files: best.files,
-		prefix: best.dir
+		raw: content,
+		links: parseMarkdownLinks(content)
 	};
 }
-async function listDocsAtRef(owner, repo, ref, pathPrefix = "docs/") {
-	return filterDocFiles(await listFilesAtRef(owner, repo, ref), pathPrefix);
+function parseMarkdownLinks(content) {
+	return extractLinks(content).filter((l) => l.url.endsWith(".md"));
 }
-async function fetchGitDocs(owner, repo, version, packageName, repoUrl) {
-	const override = packageName ? getDocOverride(packageName) : void 0;
-	if (override) {
-		const ref = override.ref || "main";
-		const fallback = !override.ref;
-		const files = await listDocsAtRef(override.owner, override.repo, ref, `${override.path}/`);
-		if (files.length === 0) return null;
-		return {
-			baseUrl: `https://raw.githubusercontent.com/${override.owner}/${override.repo}/${ref}`,
-			ref,
-			files,
-			fallback,
-			docsPrefix: `${override.path}/` !== "docs/" ? `${override.path}/` : void 0
-		};
-	}
-	const tag = await findGitTag(owner, repo, version, packageName, repoUrl ? extractBranchHint(repoUrl) : void 0);
-	if (!tag) return null;
-	let docs = filterDocFiles(tag.files, "docs/");
-	let docsPrefix;
-	let allFiles;
-	if (docs.length === 0) {
-		const discovered = discoverDocFiles(tag.files, packageName);
-		if (discovered) {
-			docs = discovered.files;
-			docsPrefix = discovered.prefix || void 0;
-			allFiles = tag.files;
-		}
+function isSafeUrl(url) {
+	try {
+		const parsed = new URL(url);
+		if (parsed.protocol !== "https:") return false;
+		const host = parsed.hostname;
+		if (host === "localhost" || host === "0.0.0.0" || host === "[::1]") return false;
+		if (/^(?:127\.|10\.|172\.(?:1[6-9]|2\d|3[01])\.|192\.168\.|169\.254\.)/.test(host)) return false;
+		if (/^\[(?:f[cd]|fe[89ab]|::ffff:)/i.test(host)) return false;
+		return true;
+	} catch {
+		return false;
 	}
-	docs = filterFrameworkDocs(docs, packageName);
-	if (docs.length === 0) return null;
-	return {
-		baseUrl: `https://raw.githubusercontent.com/${owner}/${repo}/${tag.ref}`,
-		ref: tag.ref,
-		files: docs,
-		docsPrefix,
-		allFiles,
-		fallback: tag.fallback
-	};
 }
-function normalizePath(p) {
-	return p.replace(/^\//, "").replace(/\.(?:md|mdx)$/, "");
+async function downloadLlmsDocs(llmsContent, baseUrl, onProgress) {
+	const limit = pLimit(5);
+	let completed = 0;
+	return (await Promise.all(llmsContent.links.map((link) => limit(async () => {
+		const url = link.url.startsWith("http") ? link.url : `${baseUrl.replace(/\/$/, "")}${link.url.startsWith("/") ? "" : "/"}${link.url}`;
+		if (!isSafeUrl(url)) return null;
+		const content = await fetchText(url);
+		onProgress?.(link.url, ++completed, llmsContent.links.length);
+		if (content && content.length > 100) return {
+			url: link.url.startsWith("http") ? new URL(link.url).pathname : link.url,
+			title: link.title,
+			content
+		};
+		return null;
+	})))).filter((d) => d !== null);
 }
-function validateGitDocsWithLlms(llmsLinks, repoFiles) {
-	if (llmsLinks.length === 0) return {
-		isValid: true,
-		matchRatio: 1
-	};
-	const sample = llmsLinks.slice(0, 10);
-	const normalizedLinks = sample.map((link) => {
-		let path = link.url;
-		if (path.startsWith("http")) try {
-			path = new URL(path).pathname;
-		} catch {}
-		return normalizePath(path);
-	});
-	const repoNormalized = new Set(repoFiles.map(normalizePath));
-	let matches = 0;
-	for (const linkPath of normalizedLinks) for (const repoPath of repoNormalized) if (repoPath === linkPath || repoPath.endsWith(`/${linkPath}`)) {
-		matches++;
-		break;
+function normalizeLlmsLinks(content, baseUrl) {
+	let normalized = content;
+	if (baseUrl) {
+		const escaped = baseUrl.replace(/\/$/, "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		normalized = normalized.replace(new RegExp(`\\]\\(${escaped}(/[^)]+\\.md)\\)`, "g"), "](./docs$1)");
 	}
-	const matchRatio = matches / sample.length;
-	return {
-		isValid: matchRatio >= .3,
-		matchRatio
-	};
+	normalized = normalized.replace(/\]\(\/([^)]+\.md)\)/g, "](./docs/$1)");
+	return normalized;
+}
+function extractSections(content, patterns) {
+	const sections = [];
+	const parts = content.split(/\n---\n/);
+	for (const part of parts) {
+		const urlMatch = part.match(/^url: *(\S.*)$/m);
+		if (!urlMatch) continue;
+		const url = urlMatch[1];
+		if (patterns.some((p) => url.includes(p))) {
+			const contentStart = part.indexOf("\n", part.indexOf("url:"));
+			if (contentStart > -1) sections.push(part.slice(contentStart + 1));
+		}
+	}
+	if (sections.length === 0) return null;
+	return sections.join("\n\n---\n\n");
 }
 async function verifyNpmRepo(owner, repo, packageName) {
 	const base = `https://raw.githubusercontent.com/${owner}/${repo}/HEAD`;
@@ -2062,6 +2073,17 @@ async function fetchGitLabSkills(source, onProgress) {
 		});
 	}
 }
+async function resolveLocalDep(packageName, cwd) {
+	const result = readPackageJsonSafe(join(cwd, "package.json"));
+	if (!result) return null;
+	const pkg = result.parsed;
+	const depVersion = {
+		...pkg.dependencies,
+		...pkg.devDependencies
+	}[packageName];
+	if (!depVersion?.startsWith("link:")) return null;
+	return resolveLocalPackageDocs(resolve(cwd, depVersion.slice(5)));
+}
 async function searchNpmPackages(query, size = 5) {
 	const data = await $fetch(`https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(query)}&size=${size}`).catch(() => null);
 	if (!data?.objects?.length) return [];
@@ -2472,6 +2494,161 @@ function getInstalledSkillVersion(skillDir) {
 	if (!existsSync(skillPath)) return null;
 	return readFileSync(skillPath, "utf-8").match(/^version:\s*"?([^"\n]+)"?/m)?.[1] || null;
 }
-export { fetchText as $, filterFrameworkDocs as A, fetchGitHubIssues as B, toCrawlPattern as C, fetchGitHubRepoMeta as D, fetchGitDocs as E, extractSections as F, compareSemver as G, generateIssueIndex as H, fetchLlmsTxt as I, isPrerelease as J, fetchReleaseNotes as K, fetchLlmsUrl as L, resolveGitHubRepo as M, validateGitDocsWithLlms as N, fetchReadme as O, downloadLlmsDocs as P, fetchGitHubRaw as Q, normalizeLlmsLinks as R, fetchCrawledDocs as S, MIN_GIT_DOCS as T, isGhAvailable as U, formatIssueAsMarkdown as V, fetchBlogReleases as W, $fetch as X, parseSemver as Y, extractBranchHint as Z, resolveEntryFiles as _, getInstalledSkillVersion as a, verifyUrl as at, formatDiscussionAsMarkdown as b, readLocalPackageInfo as c, resolvePackageDocs as d, isGitHubRepoUrl as et, resolvePackageDocsWithAttempts as f, parseSkillFrontmatterName as g, parseGitSkillInput as h, fetchPkgDist as i, parsePackageSpec as it, isShallowGitDocs as j, fetchReadmeContent as k, resolveInstalledVersion as l, fetchGitSkills as m, fetchNpmPackage as n, parseGitHubRepoSlug as nt, parseVersionSpecifier as o, searchNpmPackages as p, generateReleaseIndex as q, fetchNpmRegistryMeta as r, parseGitHubUrl as rt, readLocalDependencies as s, fetchLatestVersion as t, normalizeRepoUrl as tt, resolveLocalPackageDocs as u, generateDocsIndex as v, resolveCrateDocsWithAttempts as w, generateDiscussionIndex as x, fetchGitHubDiscussions as y, parseMarkdownLinks as z };
+function parseSkillInput(input) {
+	const trimmed = input.trim();
+	if (trimmed.startsWith("npm:")) {
+		const { name, tag } = splitPackageTag(trimmed.slice(4));
+		return {
+			type: "npm",
+			package: name,
+			tag
+		};
+	}
+	if (trimmed.startsWith("crate:")) {
+		const rest = trimmed.slice(6).trim();
+		const atIdx = rest.indexOf("@");
+		return {
+			type: "crate",
+			package: (atIdx === -1 ? rest : rest.slice(0, atIdx)).toLowerCase(),
+			version: atIdx === -1 ? void 0 : rest.slice(atIdx + 1) || void 0
+		};
+	}
+	if (trimmed.startsWith("gh:") || trimmed.startsWith("github:")) {
+		const rest = trimmed.startsWith("gh:") ? trimmed.slice(3) : trimmed.slice(7);
+		const gitSource = parseGitSkillInput(rest);
+		if (gitSource) return {
+			type: "git",
+			source: gitSource
+		};
+		if (/^[\w.-]+\/[\w.-]+/.test(rest)) {
+			const [owner, repo] = rest.split("/");
+			return {
+				type: "git",
+				source: {
+					type: "github",
+					owner,
+					repo
+				}
+			};
+		}
+		return {
+			type: "bare",
+			package: rest
+		};
+	}
+	if (trimmed.startsWith("@")) {
+		const rest = trimmed.slice(1);
+		if (rest.indexOf("/") === -1) return {
+			type: "curator",
+			handle: rest
+		};
+		const { name, tag } = splitPackageTag(trimmed);
+		return {
+			type: "bare",
+			package: name,
+			tag
+		};
+	}
+	const gitSource = parseGitSkillInput(trimmed);
+	if (gitSource) return {
+		type: "git",
+		source: gitSource
+	};
+	const { name, tag } = splitPackageTag(trimmed);
+	return {
+		type: "bare",
+		package: name,
+		tag
+	};
+}
+function resolveSkillName(input) {
+	const source = parseSkillInput(input);
+	switch (source.type) {
+		case "npm":
+		case "bare": return source.package;
+		case "crate": return `crate:${source.package}`;
+		case "git":
+			if (source.source.type === "github" && source.source.repo) return source.source.repo;
+			return null;
+		case "curator":
+		case "collection": return null;
+		default: throw new Error(`Unhandled SkillSource type: ${JSON.stringify(source)}`);
+	}
+}
+function toStoragePackageName(identityName) {
+	if (identityName.startsWith("crate:")) return `@skilld-crate/${identityName.slice(6)}`;
+	return identityName;
+}
+function isCrateSpec(spec) {
+	return spec.startsWith("crate:");
+}
+function toCrateIdentity(crateName) {
+	return `crate:${crateName}`;
+}
+function splitPackageTag(spec) {
+	if (spec.startsWith("@")) {
+		const slashIdx = spec.indexOf("/");
+		if (slashIdx !== -1) {
+			const afterSlash = spec.indexOf("@", slashIdx);
+			if (afterSlash !== -1) return {
+				name: spec.slice(0, afterSlash),
+				tag: spec.slice(afterSlash + 1) || void 0
+			};
+		}
+		return { name: spec };
+	}
+	const atIdx = spec.indexOf("@");
+	if (atIdx !== -1) return {
+		name: spec.slice(0, atIdx),
+		tag: spec.slice(atIdx + 1) || void 0
+	};
+	return { name: spec };
+}
+const RESOLVE_STEP_LABELS = {
+	"npm": "npm registry",
+	"github-docs": "GitHub docs",
+	"github-meta": "GitHub meta",
+	"github-search": "GitHub search",
+	"readme": "README",
+	"llms.txt": "llms.txt",
+	"crawl": "website crawl",
+	"local": "node_modules"
+};
+async function resolvePackageOrCrate(packageSpec, opts) {
+	const { cwd, onProgress } = opts;
+	const isCrate = isCrateSpec(packageSpec);
+	const normalizedSpec = isCrate ? packageSpec.slice(6).trim() : packageSpec;
+	const { name: parsedName, tag: requestedTag } = parsePackageSpec(normalizedSpec);
+	const packageName = isCrate ? parsedName.toLowerCase() : parsedName;
+	const identityPackageName = isCrate ? toCrateIdentity(packageName) : packageName;
+	const storagePackageName = toStoragePackageName(identityPackageName);
+	const localDeps = isCrate ? [] : await readLocalDependencies(cwd).catch(() => []);
+	const localVersion = isCrate ? void 0 : localDeps.find((d) => d.name === packageName)?.version;
+	const resolveResult = isCrate ? await resolveCrateDocsWithAttempts(packageName, {
+		version: requestedTag,
+		onProgress
+	}) : await resolvePackageDocsWithAttempts(requestedTag ? normalizedSpec : packageName, {
+		version: localVersion,
+		cwd,
+		onProgress: (step) => onProgress?.(RESOLVE_STEP_LABELS[step] ?? step)
+	});
+	let resolved = resolveResult.package;
+	if (!resolved && !isCrate) {
+		onProgress?.(RESOLVE_STEP_LABELS.local);
+		resolved = await resolveLocalDep(packageName, cwd);
+	}
+	return {
+		packageName,
+		identityPackageName,
+		storagePackageName,
+		isCrate,
+		requestedTag,
+		localVersion,
+		resolved,
+		attempts: resolveResult.attempts,
+		registryVersion: resolveResult.registryVersion
+	};
+}
+export { fetchReleaseNotes as $, resolveCrateDocsWithAttempts as A, parseMarkdownLinks as B, resolveEntryFiles as C, generateDiscussionIndex as D, formatDiscussionAsMarkdown as E, downloadLlmsDocs as F, MIN_GIT_DOCS as G, formatIssueAsMarkdown as H, extractSections as I, isShallowGitDocs as J, fetchGitDocs as K, fetchLlmsTxt as L, fetchReadme as M, fetchReadmeContent as N, fetchCrawledDocs as O, resolveGitHubRepo as P, compareSemver as Q, fetchLlmsUrl as R, parseSkillFrontmatterName as S, fetchGitHubDiscussions as T, generateIssueIndex as U, fetchGitHubIssues as V, isGhAvailable as W, mapInsert as X, validateGitDocsWithLlms as Y, fetchBlogReleases as Z, resolvePackageDocsWithAttempts as _, toStoragePackageName as a, fetchGitHubRaw as at, fetchGitSkills as b, fetchNpmRegistryMeta as c, normalizeRepoUrl as ct, parseVersionSpecifier as d, parsePackageSpec as dt, generateReleaseIndex as et, readLocalDependencies as f, verifyUrl as ft, resolvePackageDocs as g, resolveLocalPackageDocs as h, resolveSkillName as i, extractBranchHint as it, fetchGitHubRepoMeta as j, toCrawlPattern as k, fetchPkgDist as l, parseGitHubRepoSlug as lt, resolveInstalledVersion as m, isCrateSpec as n, parseSemver as nt, fetchLatestVersion as o, fetchText as ot, readLocalPackageInfo as p, filterFrameworkDocs as q, parseSkillInput as r, $fetch as rt, fetchNpmPackage as s, isGitHubRepoUrl as st, resolvePackageOrCrate as t, isPrerelease as tt, getInstalledSkillVersion as u, parseGitHubUrl as ut, searchNpmPackages as v, generateDocsIndex as w, parseGitSkillInput as x, resolveLocalDep as y, normalizeLlmsLinks as z };
 
 //# sourceMappingURL=sources.mjs.map