skilld 1.7.2 → 1.7.4

package/dist/_chunks/sync-pipeline.mjs

@@ -0,0 +1,952 @@
+import { l as getPackageDbPath, p as skillInternalDir, u as getRepoCacheDir } from "./paths.mjs";
+import { L as updateConfig, P as readConfig, b as writeToRepoCache, h as listReferenceFiles, k as defaultFeatures, t as createReferenceCache, y as writeToCache } from "./cache.mjs";
+import { t as getCacheDir } from "./version.mjs";
+import { r as resolvePkgDir } from "./prepare.mjs";
+import { n as sanitizeMarkdown } from "./sanitize.mjs";
+import { i as parseFrontmatter } from "./markdown.mjs";
+import { o as listIndexIds, r as createIndex, t as SearchDepsUnavailableError } from "./retriv.mjs";
+import { o as getPrereleaseChangelogRef, t as getBlogPreset } from "./package-registry.mjs";
+import { $ as fetchReleaseNotes, C as resolveEntryFiles, D as generateDiscussionIndex, E as formatDiscussionAsMarkdown, F as downloadLlmsDocs, H as formatIssueAsMarkdown, J as isShallowGitDocs, K as fetchGitDocs, L as fetchLlmsTxt, N as fetchReadmeContent, O as fetchCrawledDocs, T as fetchGitHubDiscussions, U as generateIssueIndex, V as fetchGitHubIssues, W as isGhAvailable, Z as fetchBlogReleases, at as fetchGitHubRaw, et as generateReleaseIndex, k as toCrawlPattern, q as filterFrameworkDocs, s as fetchNpmPackage, tt as isPrerelease, ut as parseGitHubUrl, w as generateDocsIndex, z as normalizeLlmsLinks } from "./sources.mjs";
+import { a as getModelName, i as getModelLabel, o as createToolProgress, r as getAvailableModels, t as optimizeDocs } from "./agent.mjs";
+import { D as maxItems, E as SECTION_OUTPUT_FILES, O as maxLines, T as SECTION_MERGE_ORDER, n as writeGeneratedSkillMd, w as wrapSection, y as buildAllSectionPrompts } from "./prompts.mjs";
+import { g as pickModel, n as NO_MODELS_MESSAGE, p as isInteractive } from "./cli-helpers.mjs";
+import { c as readLock, t as buildPackageDirMap } from "./lockfile.mjs";
+import { t as semverDiff } from "./semver.mjs";
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { join, relative } from "pathe";
+import * as p from "@clack/prompts";
+const RATE_LIMIT_RE = /\b429\b|rate.?limit|exhausted.*capacity|quota.*reset/i;
+async function runSkillEnhancement(ctx, run, onProgress) {
+	const { packageName, cachePackageName, version, skillDir, dirName, resolved, relatedSkills, references, packages, features, overheadLines } = ctx;
+	const { docsType, hasShippedDocs: shippedDocs, pkgFiles, hasIssues, hasDiscussions, hasReleases, hasChangelog } = references;
+	const { model, force, debug, sections, customPrompt, eject } = run;
+	const cacheKey = cachePackageName || packageName;
+	const docFiles = listReferenceFiles(skillDir);
+	const result = await optimizeDocs({
+		packageName: cacheKey,
+		skillDir,
+		model,
+		version,
+		hasGithub: hasIssues || hasDiscussions,
+		hasReleases,
+		hasChangelog,
+		docFiles,
+		docsType,
+		hasShippedDocs: shippedDocs,
+		noCache: force,
+		debug,
+		sections,
+		customPrompt,
+		features,
+		pkgFiles,
+		overheadLines,
+		onProgress
+	});
+	if (result.wasOptimized) writeGeneratedSkillMd(skillDir, {
+		name: packageName,
+		version,
+		releasedAt: resolved.releasedAt,
+		distTags: resolved.distTags,
+		body: result.optimized,
+		relatedSkills,
+		hasIssues,
+		hasDiscussions,
+		hasReleases,
+		hasChangelog,
+		docsType,
+		hasShippedDocs: shippedDocs,
+		pkgFiles,
+		generatedBy: getModelLabel(model),
+		dirName,
+		packages,
+		repoUrl: resolved.repoUrl,
+		features,
+		eject
+	});
+	return result;
+}
+async function enhanceSkillWithLLM(ctx, run) {
+	const llmLog = p.taskLog({
+		title: `Agent exploring ${ctx.packageName}`,
+		limit: 3
+	});
+	const { wasOptimized, usage, cost, warnings, error, debugLogsDir } = await runSkillEnhancement(ctx, run, createToolProgress(llmLog));
+	if (wasOptimized) {
+		const costParts = [];
+		if (usage) {
+			const totalK = Math.round(usage.totalTokens / 1e3);
+			costParts.push(`${totalK}k tokens`);
+		}
+		if (cost) costParts.push(`$${cost.toFixed(2)}`);
+		const costSuffix = costParts.length > 0 ? ` (${costParts.join(", ")})` : "";
+		llmLog.success(`Generated best practices${costSuffix}`);
+		if (debugLogsDir) p.log.info(`Debug logs: ${relative(process.cwd(), debugLogsDir)}`);
+		if (error) p.log.warn(`\x1B[33mPartial failure: ${error}\x1B[0m`);
+		if (warnings?.length) for (const w of warnings) p.log.warn(`\x1B[33m${w}\x1B[0m`);
+	} else if (error && RATE_LIMIT_RE.test(error)) llmLog.error(`Rate limited by LLM provider. Try again shortly or use a different model via \`skilld config\``);
+	else llmLog.error(`Enhancement failed${error ? `: ${error}` : ""}`);
+}
+function writeBaseSkill(ctx, opts = {}) {
+	const { packageName, version, skillDir, dirName, references, resolved, relatedSkills, packages, features } = ctx;
+	return writeGeneratedSkillMd(skillDir, {
+		name: packageName,
+		version,
+		releasedAt: resolved.releasedAt,
+		description: resolved.description,
+		distTags: resolved.distTags,
+		body: opts.body,
+		relatedSkills,
+		hasIssues: references.hasIssues,
+		hasDiscussions: references.hasDiscussions,
+		hasReleases: references.hasReleases,
+		hasChangelog: references.hasChangelog,
+		docsType: references.docsType,
+		hasShippedDocs: references.hasShippedDocs,
+		pkgFiles: references.pkgFiles,
+		generatedBy: opts.generatedBy,
+		dirName,
+		packages,
+		repoUrl: resolved.repoUrl,
+		features,
+		eject: opts.eject
+	});
+}
+function applyCachedSections(ctx, sections, opts = {}) {
+	const cache = createReferenceCache(ctx.cachePackageName || ctx.packageName, ctx.version);
+	if (!sections.every((s) => cache.readSection(SECTION_OUTPUT_FILES[s]) !== null)) return false;
+	const parts = [];
+	for (const s of SECTION_MERGE_ORDER) {
+		if (!sections.includes(s)) continue;
+		const content = cache.readSection(SECTION_OUTPUT_FILES[s]);
+		if (content) parts.push(wrapSection(s, content));
+	}
+	writeBaseSkill(ctx, {
+		body: parts.join("\n\n"),
+		generatedBy: "cached",
+		eject: opts.eject
+	});
+	return true;
+}
+function writePromptFiles(ctx, run) {
+	const { packageName, version, skillDir, references, features, overheadLines } = ctx;
+	const { sections, customPrompt } = run;
+	const docFiles = listReferenceFiles(skillDir);
+	const prompts = buildAllSectionPrompts({
+		packageName,
+		skillDir,
+		version,
+		hasIssues: references.hasIssues,
+		hasDiscussions: references.hasDiscussions,
+		hasReleases: references.hasReleases,
+		hasChangelog: references.hasChangelog,
+		docFiles,
+		docsType: references.docsType,
+		hasShippedDocs: references.hasShippedDocs,
+		pkgFiles: references.pkgFiles,
+		customPrompt,
+		features,
+		overheadLines,
+		sections
+	});
+	const skilldDir = skillInternalDir(skillDir);
+	mkdirSync(skilldDir, { recursive: true });
+	for (const [section, prompt] of prompts) writeFileSync(join(skilldDir, `PROMPT_${section}.md`), prompt);
+	const written = [...prompts.keys()];
+	if (written.length > 0) {
+		const relDir = relative(process.cwd(), skillDir);
+		const promptFiles = written.map((s) => `PROMPT_${s}.md`).join(", ");
+		const outputFileList = written.map((s) => SECTION_OUTPUT_FILES[s]).join(", ");
+		p.log.info(`Prompt files written to ${relDir}/.skilld/\n\x1B[2m\x1B[3m  Read each prompt file (${promptFiles}) in ${relDir}/.skilld/, read the\n  referenced files, then write your output to the matching file (${outputFileList}).\n  When done, run: skilld assemble\x1B[0m`);
+	}
+	return written;
+}
+const DEFAULT_SECTIONS = ["best-practices", "api-changes"];
+async function resolveAutoModel(override, yes) {
+	if (override) return override;
+	const config = readConfig();
+	if (!yes || config.skipLlm) return void 0;
+	if (config.model) return config.model;
+	const available = await getAvailableModels();
+	return available.find((m) => m.recommended)?.id ?? available[0]?.id;
+}
+async function selectSkillSections(message = "Enhance SKILL.md") {
+	p.log.info("Budgets adapt to package release density.");
+	const selected = await p.multiselect({
+		message,
+		options: [
+			{
+				label: "API changes",
+				value: "api-changes",
+				hint: "new/deprecated APIs from version history"
+			},
+			{
+				label: "Best practices",
+				value: "best-practices",
+				hint: "gotchas, pitfalls, patterns"
+			},
+			{
+				label: "Custom section",
+				value: "custom",
+				hint: "add your own section"
+			}
+		],
+		initialValues: DEFAULT_SECTIONS,
+		required: false
+	});
+	if (p.isCancel(selected)) return {
+		sections: [],
+		cancelled: true
+	};
+	const sections = selected;
+	if (sections.length === 0) return {
+		sections: [],
+		cancelled: false
+	};
+	if (sections.length > 1) {
+		const n = sections.length;
+		const budgetLines = [];
+		for (const s of sections) switch (s) {
+			case "api-changes":
+				budgetLines.push(`  API changes     ${maxItems(6, 12, n)}–${maxItems(6, Math.round(12 * 1.6), n)} items (adapts to release churn)`);
+				break;
+			case "best-practices":
+				budgetLines.push(`  Best practices  ${maxItems(4, 10, n)}–${maxItems(4, Math.round(10 * 1.3), n)} items`);
+				break;
+			case "custom":
+				budgetLines.push(`  Custom          ≤${maxLines(50, 80, n)} lines`);
+				break;
+		}
+		p.log.info(`Budget (${n} sections):\n${budgetLines.join("\n")}`);
+	}
+	let customPrompt;
+	if (sections.includes("custom")) {
+		const heading = await p.text({
+			message: "Section heading",
+			placeholder: "e.g. \"Migration from v2\" or \"SSR Patterns\""
+		});
+		if (p.isCancel(heading)) return {
+			sections: [],
+			cancelled: true
+		};
+		const body = await p.text({
+			message: "Instructions for this section",
+			placeholder: "e.g. \"Document breaking changes and migration steps from v2 to v3\""
+		});
+		if (p.isCancel(body)) return {
+			sections: [],
+			cancelled: true
+		};
+		customPrompt = {
+			heading,
+			body
+		};
+	}
+	return {
+		sections,
+		customPrompt,
+		cancelled: false
+	};
+}
+async function selectLlmConfig(presetModel, message, updateCtx) {
+	if (presetModel) {
+		if ((await getAvailableModels()).some((m) => m.id === presetModel)) return {
+			model: presetModel,
+			sections: DEFAULT_SECTIONS
+		};
+		if (!isInteractive()) return null;
+	}
+	if (!isInteractive()) return null;
+	const config = readConfig();
+	const available = await getAvailableModels();
+	if (available.length === 0) {
+		p.log.warn(NO_MODELS_MESSAGE);
+		return null;
+	}
+	let defaultModel;
+	if (config.model && available.some((m) => m.id === config.model)) defaultModel = config.model;
+	else {
+		if (config.model) p.log.warn(`Configured model \x1B[36m${config.model}\x1B[0m is unavailable — using auto-selected fallback`);
+		defaultModel = available.find((m) => m.recommended)?.id ?? available[0].id;
+	}
+	const defaultModelName = getModelName(defaultModel);
+	const providerHint = available.find((m) => m.id === defaultModel)?.providerName ?? "";
+	const sourceHint = config.model === defaultModel ? "configured" : "recommended";
+	const defaultHint = providerHint ? `${providerHint} · ${sourceHint}` : sourceHint;
+	let enhanceMessage = message ? `${message}?` : "Enhance SKILL.md?";
+	let defaultToSkip = false;
+	if (updateCtx) {
+		const diff = updateCtx.bumpType ?? (updateCtx.oldVersion && updateCtx.newVersion ? semverDiff(updateCtx.oldVersion, updateCtx.newVersion) : null);
+		const isSmallBump = diff === "patch" || diff === "prerelease" || diff === "prepatch" || diff === "preminor" || diff === "premajor";
+		const ageParts = [];
+		if (diff) ageParts.push(diff);
+		if (updateCtx.syncedAt) {
+			const syncedAtMs = new Date(updateCtx.syncedAt).getTime();
+			if (Number.isFinite(syncedAtMs)) {
+				const days = Math.floor((Date.now() - syncedAtMs) / 864e5);
+				ageParts.push(days === 0 ? "today" : days === 1 ? "1d ago" : `${days}d ago`);
+			}
+		}
+		if (updateCtx.wasEnhanced) ageParts.push("LLM-enhanced");
+		const hint = [updateCtx.oldVersion && updateCtx.newVersion ? `${updateCtx.oldVersion} → ${updateCtx.newVersion}` : null, ...ageParts].filter(Boolean).join(" · ");
+		if (hint) enhanceMessage = `Enhance SKILL.md? \x1B[90m(${hint})\x1B[0m`;
+		if (updateCtx.wasEnhanced && isSmallBump) defaultToSkip = true;
+	}
+	const choice = await p.select({
+		message: enhanceMessage,
+		options: [
+			{
+				label: defaultModelName,
+				value: "default",
+				hint: defaultHint
+			},
+			{
+				label: "Different model",
+				value: "pick",
+				hint: "choose another enhancement model"
+			},
+			{
+				label: "Prompt only",
+				value: "prompt",
+				hint: "write prompts for manual use"
+			},
+			{
+				label: "Skip",
+				value: "skip",
+				hint: "base skill with docs, issues, and types"
+			}
+		],
+		...defaultToSkip ? { initialValue: "skip" } : {}
+	});
+	if (p.isCancel(choice)) return null;
+	if (choice === "skip") return null;
+	if (choice === "prompt") {
+		const { sections, customPrompt, cancelled } = await selectSkillSections(message ? `${message} (prompt only)` : "Select sections for prompt generation");
+		if (cancelled || sections.length === 0) return null;
+		return {
+			model: defaultModel,
+			sections,
+			customPrompt,
+			promptOnly: true
+		};
+	}
+	let model;
+	if (choice === "pick") {
+		const picked = await pickModel(available);
+		if (!picked) return null;
+		updateConfig({ model: picked });
+		model = picked;
+	} else model = defaultModel;
+	if (!model) return null;
+	const modelName = getModelName(model);
+	const { sections, customPrompt, cancelled } = await selectSkillSections(message ? `${message} (${modelName})` : `Enhance SKILL.md with ${modelName}`);
+	if (cancelled || sections.length === 0) return null;
+	return {
+		model,
+		sections,
+		customPrompt
+	};
+}
+function parentDocId(id) {
+	const idx = id.indexOf("#chunk-");
+	return idx === -1 ? id : id.slice(0, idx);
+}
+function capDocs(allDocs, max, onProgress) {
+	if (allDocs.length <= max) return;
+	const TYPE_PRIORITY = {
+		doc: 0,
+		issue: 1,
+		discussion: 2,
+		release: 3,
+		source: 4,
+		types: 5
+	};
+	allDocs.sort((a, b) => {
+		const ta = TYPE_PRIORITY[a.metadata?.type || "doc"] ?? 3;
+		const tb = TYPE_PRIORITY[b.metadata?.type || "doc"] ?? 3;
+		if (ta !== tb) return ta - tb;
+		return a.id.localeCompare(b.id);
+	});
+	onProgress(`Indexing capped at ${max}/${allDocs.length} docs (prioritized by type)`);
+	allDocs.length = max;
+}
+async function indexResources(opts) {
+	const { packageName, version, cwd, onProgress } = opts;
+	const features = opts.features ?? readConfig().features ?? defaultFeatures;
+	if (!features.search) return;
+	const dbPath = getPackageDbPath(packageName, version);
+	const dbExists = existsSync(dbPath);
+	const allDocs = [...opts.docsToIndex];
+	const pkgDir = resolvePkgDir(packageName, cwd, version);
+	if (features.search && pkgDir) {
+		onProgress("Scanning exports");
+		const entryFiles = await resolveEntryFiles(pkgDir);
+		for (const e of entryFiles) allDocs.push({
+			id: e.path,
+			content: e.content,
+			metadata: {
+				package: packageName,
+				source: `pkg/${e.path}`,
+				type: e.type
+			}
+		});
+	}
+	if (allDocs.length === 0) return;
+	capDocs(allDocs, 250, onProgress);
+	if (!dbExists) {
+		onProgress(`Building search index (${allDocs.length} docs)`);
+		try {
+			await createIndex(allDocs, {
+				dbPath,
+				onProgress: ({ phase, current, total }) => {
+					if (phase === "storing") {
+						const d = allDocs[current - 1];
+						onProgress(`Storing ${d?.metadata?.type === "source" || d?.metadata?.type === "types" ? "code" : d?.metadata?.type || "doc"} (${current}/${total})`);
+					} else if (phase === "embedding") onProgress(`Creating embeddings (${current}/${total})`);
+				}
+			});
+		} catch (err) {
+			if (err instanceof SearchDepsUnavailableError) onProgress("Search indexing skipped (native deps unavailable)");
+			else throw err;
+		}
+		return;
+	}
+	let existingIds;
+	try {
+		existingIds = await listIndexIds({ dbPath });
+	} catch (err) {
+		if (err instanceof SearchDepsUnavailableError) {
+			onProgress("Search indexing skipped (native deps unavailable)");
+			return;
+		}
+		throw err;
+	}
+	const existingParentIds = new Set(existingIds.map(parentDocId));
+	const incomingIds = new Set(allDocs.map((d) => d.id));
+	const newDocs = allDocs.filter((d) => !existingParentIds.has(d.id));
+	const removeIds = existingIds.filter((id) => !incomingIds.has(parentDocId(id)));
+	if (newDocs.length === 0 && removeIds.length === 0) {
+		onProgress("Search index up to date");
+		return;
+	}
+	const parts = [];
+	if (newDocs.length > 0) parts.push(`+${newDocs.length} new`);
+	if (removeIds.length > 0) parts.push(`-${removeIds.length} stale`);
+	onProgress(`Updating search index (${parts.join(", ")})`);
+	try {
+		await createIndex(newDocs, {
+			dbPath,
+			removeIds,
+			onProgress: ({ phase, current, total }) => {
+				if (phase === "storing") {
+					const d = newDocs[current - 1];
+					onProgress(`Storing ${d?.metadata?.type === "source" || d?.metadata?.type === "types" ? "code" : d?.metadata?.type || "doc"} (${current}/${total})`);
+				} else if (phase === "embedding") onProgress(`Creating embeddings (${current}/${total})`);
+			}
+		});
+	} catch (err) {
+		if (err instanceof SearchDepsUnavailableError) onProgress("Search indexing skipped (native deps unavailable)");
+		else throw err;
+	}
+}
+async function resolveContentDocs(opts) {
+	const { packageName, resolved, version, onProgress } = opts;
+	const docs = [];
+	const docsToIndex = [];
+	const warnings = [];
+	let docSource = resolved.readmeUrl || "readme";
+	let docsType = "readme";
+	const isFrameworkDoc = (path) => filterFrameworkDocs([path], packageName).length > 0;
+	if (resolved.gitDocsUrl && resolved.repoUrl) {
+		const gh = parseGitHubUrl(resolved.repoUrl);
+		if (gh) {
+			const r = await tryGitDocs({
+				owner: gh.owner,
+				repo: gh.repo,
+				version,
+				packageName,
+				repoUrl: resolved.repoUrl,
+				llmsUrl: resolved.llmsUrl,
+				docsUrl: resolved.docsUrl,
+				onProgress
+			});
+			if (r) {
+				docs.push(...r.docs);
+				docsToIndex.push(...r.docsToIndex);
+				if (r.warning) warnings.push(r.warning);
+				if (r.kind === "git") {
+					docSource = r.docSource;
+					docsType = "docs";
+				}
+			}
+		}
+	}
+	if (resolved.crawlUrl && docs.length === 0) {
+		onProgress("Crawling website");
+		const crawled = await fetchCrawledDocs(resolved.crawlUrl, onProgress).catch((err) => {
+			warnings.push(`Crawl failed for ${resolved.crawlUrl}: ${err?.message || err}`);
+			return [];
+		});
+		if (crawled.length === 0) warnings.push(`Crawl returned 0 docs from ${resolved.crawlUrl}`);
+		for (const doc of crawled) {
+			if (!isFrameworkDoc(doc.path)) continue;
+			docs.push(doc);
+			docsToIndex.push({
+				id: doc.path,
+				content: doc.content,
+				metadata: {
+					package: packageName,
+					source: doc.path,
+					type: "doc"
+				}
+			});
+		}
+		if (docs.length > 0) {
+			docSource = resolved.crawlUrl;
+			docsType = "docs";
+		}
+	}
+	if (resolved.llmsUrl && docs.length === 0) {
+		onProgress("Fetching llms.txt");
+		const llmsContent = await fetchLlmsTxt(resolved.llmsUrl);
+		if (llmsContent) {
+			docSource = resolved.llmsUrl;
+			docsType = "llms.txt";
+			const baseUrl = resolved.docsUrl || new URL(resolved.llmsUrl).origin;
+			docs.push({
+				path: "llms.txt",
+				content: normalizeLlmsLinks(llmsContent.raw, baseUrl)
+			});
+			if (llmsContent.links.length > 0) {
+				onProgress(`Downloading ${llmsContent.links.length} linked docs`);
+				const linked = await downloadLlmsDocs(llmsContent, baseUrl, (_url, done, total) => {
+					onProgress(`Downloading linked doc ${done + 1}/${total}`);
+				});
+				for (const doc of linked) {
+					if (!isFrameworkDoc(doc.url)) continue;
+					const cachePath = join("docs", ...(doc.url.startsWith("/") ? doc.url.slice(1) : doc.url).split("/"));
+					docs.push({
+						path: cachePath,
+						content: doc.content
+					});
+					docsToIndex.push({
+						id: doc.url,
+						content: doc.content,
+						metadata: {
+							package: packageName,
+							source: cachePath,
+							type: "doc"
+						}
+					});
+				}
+				if (linked.length > 0) docsType = "docs";
+			}
+		}
+	}
+	if (resolved.docsUrl && !docs.some((d) => d.path.startsWith("docs/"))) {
+		const crawlPattern = resolved.crawlUrl || toCrawlPattern(resolved.docsUrl);
+		onProgress("Crawling docs site");
+		const crawled = await fetchCrawledDocs(crawlPattern, onProgress, resolved.crawlUrl ? 200 : 400).catch((err) => {
+			warnings.push(`Crawl failed for ${crawlPattern}: ${err?.message || err}`);
+			return [];
+		});
+		let added = 0;
+		for (const doc of crawled) {
+			if (!isFrameworkDoc(doc.path)) continue;
+			docs.push(doc);
+			docsToIndex.push({
+				id: doc.path,
+				content: doc.content,
+				metadata: {
+					package: packageName,
+					source: doc.path,
+					type: "doc"
+				}
+			});
+			added++;
+		}
+		if (added > 0) {
+			docSource = crawlPattern;
+			docsType = "docs";
+		}
+	}
+	if (resolved.readmeUrl && docs.length === 0) {
+		onProgress("Fetching README");
+		const content = await fetchReadmeContent(resolved.readmeUrl);
+		if (content) {
+			docs.push({
+				path: "docs/README.md",
+				content
+			});
+			docsToIndex.push({
+				id: "README.md",
+				content,
+				metadata: {
+					package: packageName,
+					source: "docs/README.md",
+					type: "doc"
+				}
+			});
+		}
+	}
+	return {
+		docs,
+		docsToIndex,
+		docSource,
+		docsType,
+		warnings
+	};
+}
+async function tryGitDocs(opts) {
+	const { owner, repo, version, packageName, repoUrl, llmsUrl, docsUrl, onProgress } = opts;
+	onProgress("Fetching git docs");
+	const gitDocs = await fetchGitDocs(owner, repo, version, packageName);
+	if (!gitDocs || gitDocs.files.length === 0) return null;
+	let warning;
+	if (gitDocs.fallback) warning = `Docs fetched from ${gitDocs.ref} branch (no tag found for v${version})`;
+	const BATCH_SIZE = 20;
+	const results = [];
+	for (let i = 0; i < gitDocs.files.length; i += BATCH_SIZE) {
+		const batch = gitDocs.files.slice(i, i + BATCH_SIZE);
+		onProgress(`Downloading docs ${Math.min(i + BATCH_SIZE, gitDocs.files.length)}/${gitDocs.files.length} from ${gitDocs.ref}`);
+		const batchResults = await Promise.all(batch.map(async (file) => {
+			const content = await fetchGitHubRaw(`${gitDocs.baseUrl}/${file}`);
+			return content ? {
+				file,
+				content
+			} : null;
+		}));
+		results.push(...batchResults);
+	}
+	const docs = [];
+	const docsToIndex = [];
+	for (const r of results) {
+		if (!r) continue;
+		const stripped = gitDocs.docsPrefix ? r.file.replace(gitDocs.docsPrefix, "") : r.file;
+		const cachePath = stripped.startsWith("docs/") ? stripped : `docs/${stripped}`;
+		docs.push({
+			path: cachePath,
+			content: r.content
+		});
+		docsToIndex.push({
+			id: cachePath,
+			content: r.content,
+			metadata: {
+				package: packageName,
+				source: cachePath,
+				type: "doc"
+			}
+		});
+	}
+	if (isShallowGitDocs(docs.length) && llmsUrl) {
+		onProgress(`Shallow git-docs (${docs.length} files), trying llms.txt`);
+		return {
+			kind: "discarded",
+			docs: [],
+			docsToIndex: [],
+			docSource: "",
+			warning
+		};
+	}
+	if (llmsUrl) {
+		onProgress("Caching supplementary llms.txt");
+		const llmsContent = await fetchLlmsTxt(llmsUrl);
+		if (llmsContent) {
+			const baseUrl = docsUrl || new URL(llmsUrl).origin;
+			docs.push({
+				path: "llms.txt",
+				content: normalizeLlmsLinks(llmsContent.raw, baseUrl)
+			});
+			if (llmsContent.links.length > 0) {
+				onProgress(`Downloading ${llmsContent.links.length} supplementary docs`);
+				const supplementary = await downloadLlmsDocs(llmsContent, baseUrl, (_url, done, total) => {
+					onProgress(`Downloading supplementary doc ${done + 1}/${total}`);
+				});
+				for (const doc of supplementary) {
+					if (filterFrameworkDocs([doc.url], packageName).length === 0) continue;
+					const localPath = doc.url.startsWith("/") ? doc.url.slice(1) : doc.url;
+					docs.push({
+						path: join("llms-docs", ...localPath.split("/")),
+						content: doc.content
+					});
+				}
+			}
+		}
+	}
+	return {
+		kind: "git",
+		docs,
+		docsToIndex,
+		docSource: `${repoUrl}/tree/${gitDocs.ref}/docs`,
+		warning
+	};
+}
+async function resolveTimelineReferences(opts) {
+	const { packageName, resolved, version, features, from, onProgress } = opts;
+	const docsToIndex = [];
+	const gh = resolved.repoUrl ? parseGitHubUrl(resolved.repoUrl) : null;
+	const repoInfo = gh ? {
+		owner: gh.owner,
+		repo: gh.repo
+	} : void 0;
+	const repoCacheDir = repoInfo ? getRepoCacheDir(repoInfo.owner, repoInfo.repo) : null;
+	const cacheDir = getCacheDir(packageName, version);
+	const issuesDir = repoCacheDir ? join(repoCacheDir, "issues") : join(cacheDir, "issues");
+	const discussionsDir = repoCacheDir ? join(repoCacheDir, "discussions") : join(cacheDir, "discussions");
+	const releasesPath = repoCacheDir ? join(repoCacheDir, "releases") : join(cacheDir, "releases");
+	if (features.issues && gh && isGhAvailable() && !existsSync(issuesDir)) {
+		onProgress("Fetching issues via GitHub API");
+		const issues = await fetchGitHubIssues(gh.owner, gh.repo, 30, resolved.releasedAt, from).catch(() => []);
+		if (issues.length > 0) {
+			onProgress(`Caching ${issues.length} issues`);
+			const issueDocs = [...issues.map((issue) => ({
+				path: `issues/issue-${issue.number}.md`,
+				content: formatIssueAsMarkdown(issue)
+			})), {
+				path: "issues/_INDEX.md",
+				content: generateIssueIndex(issues)
+			}];
+			if (repoInfo) writeToRepoCache(repoInfo.owner, repoInfo.repo, issueDocs);
+			else writeToCache(packageName, version, issueDocs);
+			for (const issue of issues) docsToIndex.push({
+				id: `issue-${issue.number}`,
+				content: sanitizeMarkdown(`#${issue.number}: ${issue.title}\n\n${issue.body || ""}`),
+				metadata: {
+					package: packageName,
+					source: `issues/issue-${issue.number}.md`,
+					type: "issue",
+					number: issue.number
+				}
+			});
+		}
+	}
+	if (features.discussions && gh && isGhAvailable() && !existsSync(discussionsDir)) {
+		onProgress("Fetching discussions via GitHub API");
+		const discussions = await fetchGitHubDiscussions(gh.owner, gh.repo, 20, resolved.releasedAt, from).catch(() => []);
+		if (discussions.length > 0) {
+			onProgress(`Caching ${discussions.length} discussions`);
+			const discussionDocs = [...discussions.map((d) => ({
+				path: `discussions/discussion-${d.number}.md`,
+				content: formatDiscussionAsMarkdown(d)
+			})), {
+				path: "discussions/_INDEX.md",
+				content: generateDiscussionIndex(discussions)
+			}];
+			if (repoInfo) writeToRepoCache(repoInfo.owner, repoInfo.repo, discussionDocs);
+			else writeToCache(packageName, version, discussionDocs);
+			for (const d of discussions) docsToIndex.push({
+				id: `discussion-${d.number}`,
+				content: sanitizeMarkdown(`#${d.number}: ${d.title}\n\n${d.body || ""}`),
+				metadata: {
+					package: packageName,
+					source: `discussions/discussion-${d.number}.md`,
+					type: "discussion",
+					number: d.number
+				}
+			});
+		}
+	}
+	if (features.releases && gh && isGhAvailable() && !existsSync(releasesPath)) {
+		onProgress("Fetching releases via GitHub API");
+		const changelogRef = isPrerelease(version) ? getPrereleaseChangelogRef(packageName) : void 0;
+		const releaseDocs = await fetchReleaseNotes(gh.owner, gh.repo, version, resolved.gitRef, packageName, from, changelogRef).catch(() => []);
+		let blogDocs = [];
+		if (getBlogPreset(packageName)) {
+			onProgress("Fetching blog release notes");
+			blogDocs = await fetchBlogReleases(packageName, version).catch(() => []);
+		}
+		const allDocs = [...releaseDocs, ...blogDocs];
+		const blogEntries = blogDocs.filter((d) => !d.path.endsWith("_INDEX.md")).map((d) => {
+			const versionMatch = d.path.match(/blog-(.+)\.md$/);
+			const fm = parseFrontmatter(d.content);
+			return {
+				version: versionMatch?.[1] ?? "",
+				title: fm.title ?? `Release ${versionMatch?.[1]}`,
+				date: fm.date ?? ""
+			};
+		}).filter((b) => b.version);
+		const ghReleases = releaseDocs.filter((d) => d.path.startsWith("releases/") && !d.path.endsWith("CHANGELOG.md")).map((d) => {
+			const fm = parseFrontmatter(d.content);
+			const tag = fm.tag ?? "";
+			const name = fm.name ?? tag;
+			const published = fm.published ?? "";
+			return {
+				id: 0,
+				tag,
+				name,
+				prerelease: false,
+				createdAt: published,
+				publishedAt: published,
+				markdown: ""
+			};
+		}).filter((r) => r.tag);
+		const hasChangelog = allDocs.some((d) => d.path === "releases/CHANGELOG.md");
+		if (ghReleases.length > 0 || blogEntries.length > 0) allDocs.push({
+			path: "releases/_INDEX.md",
+			content: generateReleaseIndex({
+				releases: ghReleases,
+				packageName,
+				blogReleases: blogEntries,
+				hasChangelog
+			})
+		});
+		if (allDocs.length > 0) {
+			onProgress(`Caching ${allDocs.length} releases`);
+			if (repoInfo) writeToRepoCache(repoInfo.owner, repoInfo.repo, allDocs);
+			else writeToCache(packageName, version, allDocs);
+			for (const doc of allDocs) docsToIndex.push({
+				id: doc.path,
+				content: doc.content,
+				metadata: {
+					package: packageName,
+					source: doc.path,
+					type: "release"
+				}
+			});
+		}
+	}
+	return {
+		docsToIndex,
+		hasIssues: features.issues && existsSync(issuesDir),
+		hasDiscussions: features.discussions && existsSync(discussionsDir),
+		hasReleases: features.releases && existsSync(releasesPath),
+		repoInfo
+	};
+}
+async function findRelatedSkills(packageName, skillsDir) {
+	const related = [];
+	const npmInfo = await fetchNpmPackage(packageName);
+	if (!npmInfo?.dependencies) return related;
+	const deps = new Set(Object.keys(npmInfo.dependencies));
+	if (!existsSync(skillsDir)) return related;
+	const lock = readLock(skillsDir);
+	const pkgToDirName = lock ? buildPackageDirMap(lock) : /* @__PURE__ */ new Map();
+	const installedSet = new Set(readdirSync(skillsDir));
+	for (const dep of deps) {
+		const dirName = pkgToDirName.get(dep);
+		if (dirName && installedSet.has(dirName)) related.push(dirName);
+	}
+	return related.slice(0, 5);
+}
+function detectChangelog(pkgDir, cacheDir) {
+	if (pkgDir) {
+		const found = ["CHANGELOG.md", "changelog.md"].find((f) => existsSync(join(pkgDir, f)));
+		if (found) return `pkg/${found}`;
+	}
+	if (cacheDir && existsSync(join(cacheDir, "releases", "CHANGELOG.md"))) return "releases/CHANGELOG.md";
+	return false;
+}
+async function fetchAndCacheResources(opts) {
+	const { packageName, resolved, version, onProgress } = opts;
+	const features = opts.features ?? readConfig().features ?? defaultFeatures;
+	const cache = createReferenceCache(packageName, version);
+	const cacheInvalidated = opts.useCache && resolved.crawlUrl && cache.detectDocs(resolved.repoUrl, resolved.llmsUrl).docsType === "readme";
+	const useCache = opts.useCache && !cacheInvalidated;
+	let docSource = resolved.readmeUrl || "readme";
+	let docsType = "readme";
+	const docsToIndex = [];
+	const warnings = [];
+	if (cacheInvalidated) warnings.push(`Retrying crawl for ${resolved.crawlUrl} (previous attempt only cached README)`);
+	if (!useCache) {
+		const content = await resolveContentDocs({
+			packageName,
+			resolved,
+			version,
+			onProgress
+		});
+		docSource = content.docSource;
+		docsType = content.docsType;
+		docsToIndex.push(...content.docsToIndex);
+		warnings.push(...content.warnings);
+		if (content.docs.length > 0) {
+			cache.write(content.docs);
+			if (docsType !== "readme" && content.docs.filter((d) => d.path.startsWith("docs/") && d.path.endsWith(".md")).length > 1) {
+				const docsIndex = generateDocsIndex(content.docs);
+				if (docsIndex) cache.write([{
+					path: "docs/_INDEX.md",
+					content: docsIndex
+				}]);
+			}
+		}
+	} else {
+		const cached = cache.load({
+			repoUrl: resolved.repoUrl,
+			llmsUrl: resolved.llmsUrl,
+			readmeUrl: resolved.readmeUrl,
+			onProgress,
+			generateDocsIndex
+		});
+		docsType = cached.docsType;
+		docSource = cached.docSource;
+		docsToIndex.push(...cached.docsToIndex);
+		if (cached.backfillIndex) cache.write([cached.backfillIndex]);
+	}
+	const timeline = await resolveTimelineReferences({
+		packageName,
+		resolved,
+		version,
+		features,
+		from: opts.from,
+		onProgress
+	});
+	docsToIndex.push(...timeline.docsToIndex);
+	return {
+		docSource,
+		docsType,
+		docsToIndex,
+		hasIssues: timeline.hasIssues,
+		hasDiscussions: timeline.hasDiscussions,
+		hasReleases: timeline.hasReleases,
+		warnings,
+		repoInfo: timeline.repoInfo,
+		usedCache: useCache
+	};
+}
+async function prepareSkillReferences(opts) {
+	const { packageName, version, cwd, skillDir, resources, features, baseDir, onIndexProgress } = opts;
+	const cache = createReferenceCache(packageName, version);
+	cache.linkInto(skillDir, cwd, resources.docsType, {
+		features,
+		repoInfo: resources.repoInfo
+	});
+	if (features.search) await indexResources({
+		packageName,
+		version,
+		cwd,
+		docsToIndex: resources.docsToIndex,
+		features,
+		onProgress: onIndexProgress ?? (() => {})
+	});
+	return {
+		hasChangelog: detectChangelog(cache.pkgDir(cwd), cache.dir),
+		shippedDocs: cache.hasShipped(cwd),
+		pkgFiles: cache.keyFiles(cwd),
+		relatedSkills: baseDir ? await findRelatedSkills(packageName, baseDir) : []
+	};
+}
+function buildSkillContext(opts) {
+	const { packages, cachePackageName, packageName } = opts;
+	return {
+		packageName,
+		...cachePackageName && cachePackageName !== packageName ? { cachePackageName } : {},
+		version: opts.version,
+		skillDir: opts.skillDir,
+		dirName: opts.skillDirName,
+		references: {
+			docsType: opts.resources.docsType,
+			hasShippedDocs: opts.prepared.shippedDocs,
+			pkgFiles: opts.prepared.pkgFiles,
+			hasIssues: opts.resources.hasIssues,
+			hasDiscussions: opts.resources.hasDiscussions,
+			hasReleases: opts.resources.hasReleases,
+			hasChangelog: opts.prepared.hasChangelog
+		},
+		resolved: opts.resolved,
+		relatedSkills: opts.prepared.relatedSkills,
+		packages: packages && packages.length > 1 ? packages : void 0,
+		features: opts.features,
+		overheadLines: opts.overheadLines
+	};
+}
+export { prepareSkillReferences as a, resolveAutoModel as c, applyCachedSections as d, enhanceSkillWithLLM as f, writePromptFiles as h, findRelatedSkills as i, selectLlmConfig as l, writeBaseSkill as m, detectChangelog as n, indexResources as o, runSkillEnhancement as p, fetchAndCacheResources as r, DEFAULT_SECTIONS as s, buildSkillContext as t, selectSkillSections as u };
+
+//# sourceMappingURL=sync-pipeline.mjs.map