skilld 1.7.3 → 2.0.0

package/dist/_chunks/pipeline.mjs

@@ -0,0 +1,985 @@
+import { a as getModelName, i as getModelLabel, o as createToolProgress, r as getAvailableModels, t as optimizeDocs } from "./agent.mjs";
+import { C as SECTION_OUTPUT_FILES, E as getBlogPreset, S as SECTION_MERGE_ORDER, T as maxLines, _ as buildAllSectionPrompts, k as getPrereleaseChangelogRef, t as writeGeneratedSkillMd, w as maxItems, x as wrapSection } from "./prompts.mjs";
+import { d as getRepoCacheDir, m as skillInternalDir, u as getPackageDbPath } from "./paths.mjs";
+import { n as sanitizeMarkdown } from "./sanitize.mjs";
+import { a as resolvePkgDir, s as getCacheDir } from "./prepare.mjs";
+import { a as writeToRepoCache, d as readConfig, i as listReferenceFiles, m as updateConfig, o as defaultFeatures, t as createReferenceCache } from "./cache.mjs";
+import { t as isInteractive } from "./env.mjs";
+import { r as pickModel, t as NO_MODELS_MESSAGE } from "./model-picker.mjs";
+import { A as fetchGitHubIssues, B as fetchBlogReleases, C as fetchCrawledDocs, D as downloadLlmsDocs, F as filterFrameworkDocs, H as generateReleaseIndex, I as isShallowGitDocs, M as generateIssueIndex, N as isGhAvailable, O as fetchLlmsTxt, P as fetchGitDocs, R as parseGitHubUrl, S as generateDiscussionIndex, T as fetchReadmeContent, U as isPrerelease, V as fetchReleaseNotes, W as fetchGitHubRaw, b as fetchGitHubDiscussions, d as fetchNpmPackage, j as formatIssueAsMarkdown, k as normalizeLlmsLinks, t as semverDiff, v as resolveEntryFiles, w as toCrawlPattern, x as formatDiscussionAsMarkdown, y as generateDocsIndex } from "./semver.mjs";
+import { i as parseFrontmatter } from "./markdown.mjs";
+import { c as readLock, t as buildPackageDirMap } from "./lockfile.mjs";
+import { a as listIndexIds, r as createIndex, t as SearchDepsUnavailableError } from "./retriv2.mjs";
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { styleText } from "node:util";
+import * as p from "@clack/prompts";
+import { join, relative } from "pathe";
+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(styleText("yellow", `Partial failure: ${error}`));
+		if (warnings?.length) for (const w of warnings) p.log.warn(styleText("yellow", w));
+	} 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${styleText(["dim", "italic"], `  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`)}`);
+	}
+	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 ${styleText("cyan", config.model)} 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? ${styleText("gray", `(${hint})`)}`;
+		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;
+	}
+}
+function defineStep(step) {
+	return step;
+}
+async function walkSteps(steps, ctx) {
+	for (const step of steps) {
+		if (step.canResolve && !step.canResolve(ctx)) continue;
+		await step.run(ctx);
+	}
+}
+const crawlUrlStep = defineStep({
+	id: "crawl-url",
+	canResolve: (ctx) => !!ctx.resolved.crawlUrl && ctx.docs.length === 0,
+	async run(ctx) {
+		const crawlUrl = ctx.resolved.crawlUrl;
+		ctx.onProgress("Crawling website");
+		const crawled = await fetchCrawledDocs(crawlUrl, ctx.onProgress).catch((err) => {
+			ctx.warnings.push(`Crawl failed for ${crawlUrl}: ${err?.message || err}`);
+			return [];
+		});
+		if (crawled.length === 0) ctx.warnings.push(`Crawl returned 0 docs from ${crawlUrl}`);
+		let added = 0;
+		for (const doc of crawled) {
+			if (!ctx.isFrameworkDoc(doc.path)) continue;
+			ctx.docs.push(doc);
+			ctx.docsToIndex.push({
+				id: doc.path,
+				content: doc.content,
+				metadata: {
+					package: ctx.packageName,
+					source: doc.path,
+					type: "doc"
+				}
+			});
+			added++;
+		}
+		if (added > 0) {
+			ctx.docSource = crawlUrl;
+			ctx.docsType = "docs";
+		}
+	}
+});
+const docsCrawlStep = defineStep({
+	id: "docs-crawl",
+	canResolve: (ctx) => !!ctx.resolved.docsUrl && !ctx.docs.some((d) => d.path.startsWith("docs/")),
+	async run(ctx) {
+		const crawlPattern = ctx.resolved.crawlUrl || toCrawlPattern(ctx.resolved.docsUrl);
+		ctx.onProgress("Crawling docs site");
+		const maxPages = ctx.resolved.crawlUrl ? 200 : 400;
+		const crawled = await fetchCrawledDocs(crawlPattern, ctx.onProgress, maxPages).catch((err) => {
+			ctx.warnings.push(`Crawl failed for ${crawlPattern}: ${err?.message || err}`);
+			return [];
+		});
+		let added = 0;
+		for (const doc of crawled) {
+			if (!ctx.isFrameworkDoc(doc.path)) continue;
+			ctx.docs.push(doc);
+			ctx.docsToIndex.push({
+				id: doc.path,
+				content: doc.content,
+				metadata: {
+					package: ctx.packageName,
+					source: doc.path,
+					type: "doc"
+				}
+			});
+			added++;
+		}
+		if (added > 0) {
+			ctx.docSource = crawlPattern;
+			ctx.docsType = "docs";
+		}
+	}
+});
+const BATCH_SIZE = 20;
+const defaultContentSteps = [
+	defineStep({
+		id: "git-docs",
+		canResolve: (ctx) => !!ctx.resolved.gitDocsUrl && !!ctx.resolved.repoUrl,
+		async run(ctx) {
+			const gh = parseGitHubUrl(ctx.resolved.repoUrl);
+			if (!gh) return;
+			ctx.onProgress("Fetching git docs");
+			const gitDocs = await fetchGitDocs(gh.owner, gh.repo, ctx.version, ctx.packageName);
+			if (!gitDocs || gitDocs.files.length === 0) return;
+			if (gitDocs.fallback) ctx.warnings.push(`Docs fetched from ${gitDocs.ref} branch (no tag found for v${ctx.version})`);
+			const results = [];
+			for (let i = 0; i < gitDocs.files.length; i += BATCH_SIZE) {
+				const batch = gitDocs.files.slice(i, i + BATCH_SIZE);
+				ctx.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: ctx.packageName,
+						source: cachePath,
+						type: "doc"
+					}
+				});
+			}
+			if (isShallowGitDocs(docs.length) && ctx.resolved.llmsUrl) {
+				ctx.onProgress(`Shallow git-docs (${docs.length} files), trying llms.txt`);
+				return;
+			}
+			ctx.docs.push(...docs);
+			ctx.docsToIndex.push(...docsToIndex);
+			ctx.docSource = `${ctx.resolved.repoUrl}/tree/${gitDocs.ref}/docs`;
+			ctx.docsType = "docs";
+			if (ctx.resolved.llmsUrl) {
+				ctx.onProgress("Caching supplementary llms.txt");
+				const llmsContent = await fetchLlmsTxt(ctx.resolved.llmsUrl);
+				if (llmsContent) {
+					const baseUrl = ctx.resolved.docsUrl || new URL(ctx.resolved.llmsUrl).origin;
+					ctx.docs.push({
+						path: "llms.txt",
+						content: normalizeLlmsLinks(llmsContent.raw, baseUrl)
+					});
+					if (llmsContent.links.length > 0) {
+						ctx.onProgress(`Downloading ${llmsContent.links.length} supplementary docs`);
+						const supplementary = await downloadLlmsDocs(llmsContent, baseUrl, (_url, done, total) => {
+							ctx.onProgress(`Downloading supplementary doc ${done + 1}/${total}`);
+						});
+						for (const doc of supplementary) {
+							if (!ctx.isFrameworkDoc(doc.url)) continue;
+							const localPath = doc.url.startsWith("/") ? doc.url.slice(1) : doc.url;
+							ctx.docs.push({
+								path: join("llms-docs", ...localPath.split("/")),
+								content: doc.content
+							});
+						}
+					}
+				}
+			}
+		}
+	}),
+	crawlUrlStep,
+	defineStep({
+		id: "llms.txt",
+		canResolve: (ctx) => !!ctx.resolved.llmsUrl && ctx.docs.length === 0,
+		async run(ctx) {
+			const llmsUrl = ctx.resolved.llmsUrl;
+			ctx.onProgress("Fetching llms.txt");
+			const llmsContent = await fetchLlmsTxt(llmsUrl);
+			if (!llmsContent) return;
+			ctx.docSource = llmsUrl;
+			ctx.docsType = "llms.txt";
+			const baseUrl = ctx.resolved.docsUrl || new URL(llmsUrl).origin;
+			ctx.docs.push({
+				path: "llms.txt",
+				content: normalizeLlmsLinks(llmsContent.raw, baseUrl)
+			});
+			if (llmsContent.links.length > 0) {
+				ctx.onProgress(`Downloading ${llmsContent.links.length} linked docs`);
+				const linked = await downloadLlmsDocs(llmsContent, baseUrl, (_url, done, total) => {
+					ctx.onProgress(`Downloading linked doc ${done + 1}/${total}`);
+				});
+				for (const doc of linked) {
+					if (!ctx.isFrameworkDoc(doc.url)) continue;
+					const cachePath = join("docs", ...(doc.url.startsWith("/") ? doc.url.slice(1) : doc.url).split("/"));
+					ctx.docs.push({
+						path: cachePath,
+						content: doc.content
+					});
+					ctx.docsToIndex.push({
+						id: doc.url,
+						content: doc.content,
+						metadata: {
+							package: ctx.packageName,
+							source: cachePath,
+							type: "doc"
+						}
+					});
+				}
+				if (linked.length > 0) ctx.docsType = "docs";
+			}
+		}
+	}),
+	docsCrawlStep,
+	defineStep({
+		id: "readme",
+		canResolve: (ctx) => !!ctx.resolved.readmeUrl && ctx.docs.length === 0,
+		async run(ctx) {
+			ctx.onProgress("Fetching README");
+			const content = await fetchReadmeContent(ctx.resolved.readmeUrl);
+			if (!content) return;
+			ctx.docs.push({
+				path: "docs/README.md",
+				content
+			});
+			ctx.docsToIndex.push({
+				id: "README.md",
+				content,
+				metadata: {
+					package: ctx.packageName,
+					source: "docs/README.md",
+					type: "doc"
+				}
+			});
+		}
+	})
+];
+async function resolveContentDocs(opts) {
+	const { packageName, resolved, version, onProgress } = opts;
+	const ctx = {
+		packageName,
+		resolved,
+		version,
+		onProgress,
+		isFrameworkDoc: (path) => filterFrameworkDocs([path], packageName).length > 0,
+		docs: [],
+		docsToIndex: [],
+		warnings: [],
+		docSource: resolved.readmeUrl || "readme",
+		docsType: "readme"
+	};
+	await walkSteps(defaultContentSteps, ctx);
+	return {
+		docs: ctx.docs,
+		docsToIndex: ctx.docsToIndex,
+		docSource: ctx.docSource,
+		docsType: ctx.docsType,
+		warnings: ctx.warnings
+	};
+}
+const discussionsStep = defineStep({
+	id: "discussions",
+	canResolve: (ctx) => ctx.features.discussions && !!ctx.repoInfo && isGhAvailable() && !existsSync(ctx.discussionsDir),
+	async run(ctx) {
+		const { owner, repo } = ctx.repoInfo;
+		ctx.onProgress("Fetching discussions via GitHub API");
+		const discussions = await fetchGitHubDiscussions(owner, repo, 20, ctx.resolved.releasedAt, ctx.from).catch(() => []);
+		if (discussions.length === 0) return;
+		ctx.onProgress(`Caching ${discussions.length} discussions`);
+		writeToRepoCache(owner, repo, [...discussions.map((d) => ({
+			path: `discussions/discussion-${d.number}.md`,
+			content: formatDiscussionAsMarkdown(d)
+		})), {
+			path: "discussions/_INDEX.md",
+			content: generateDiscussionIndex(discussions)
+		}]);
+		for (const d of discussions) ctx.docsToIndex.push({
+			id: `discussion-${d.number}`,
+			content: sanitizeMarkdown(`#${d.number}: ${d.title}\n\n${d.body || ""}`),
+			metadata: {
+				package: ctx.packageName,
+				source: `discussions/discussion-${d.number}.md`,
+				type: "discussion",
+				number: d.number
+			}
+		});
+	}
+});
+const issuesStep = defineStep({
+	id: "issues",
+	canResolve: (ctx) => ctx.features.issues && !!ctx.repoInfo && isGhAvailable() && !existsSync(ctx.issuesDir),
+	async run(ctx) {
+		const { owner, repo } = ctx.repoInfo;
+		ctx.onProgress("Fetching issues via GitHub API");
+		const issues = await fetchGitHubIssues(owner, repo, 30, ctx.resolved.releasedAt, ctx.from).catch(() => []);
+		if (issues.length === 0) return;
+		ctx.onProgress(`Caching ${issues.length} issues`);
+		writeToRepoCache(owner, repo, [...issues.map((issue) => ({
+			path: `issues/issue-${issue.number}.md`,
+			content: formatIssueAsMarkdown(issue)
+		})), {
+			path: "issues/_INDEX.md",
+			content: generateIssueIndex(issues)
+		}]);
+		for (const issue of issues) ctx.docsToIndex.push({
+			id: `issue-${issue.number}`,
+			content: sanitizeMarkdown(`#${issue.number}: ${issue.title}\n\n${issue.body || ""}`),
+			metadata: {
+				package: ctx.packageName,
+				source: `issues/issue-${issue.number}.md`,
+				type: "issue",
+				number: issue.number
+			}
+		});
+	}
+});
+const BLOG_VERSION_RE = /blog-(.+)\.md$/;
+const defaultTimelineSteps = [
+	issuesStep,
+	discussionsStep,
+	defineStep({
+		id: "releases",
+		canResolve: (ctx) => ctx.features.releases && !!ctx.repoInfo && isGhAvailable() && !existsSync(ctx.releasesPath),
+		async run(ctx) {
+			const { owner, repo } = ctx.repoInfo;
+			const { packageName, version, resolved, from } = ctx;
+			ctx.onProgress("Fetching releases via GitHub API");
+			const changelogRef = isPrerelease(version) ? getPrereleaseChangelogRef(packageName) : void 0;
+			const releaseDocs = await fetchReleaseNotes(owner, repo, version, resolved.gitRef, packageName, from, changelogRef).catch(() => []);
+			let blogDocs = [];
+			if (getBlogPreset(packageName)) {
+				ctx.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_VERSION_RE);
+				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) return;
+			ctx.onProgress(`Caching ${allDocs.length} releases`);
+			writeToRepoCache(owner, repo, allDocs);
+			for (const doc of allDocs) ctx.docsToIndex.push({
+				id: doc.path,
+				content: doc.content,
+				metadata: {
+					package: packageName,
+					source: doc.path,
+					type: "release"
+				}
+			});
+		}
+	})
+];
+async function resolveTimelineReferences(opts) {
+	const { packageName, resolved, version, features, from, onProgress } = opts;
+	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 ctx = {
+		packageName,
+		version,
+		resolved,
+		features,
+		from,
+		onProgress,
+		repoInfo,
+		issuesDir: repoCacheDir ? join(repoCacheDir, "issues") : join(cacheDir, "issues"),
+		discussionsDir: repoCacheDir ? join(repoCacheDir, "discussions") : join(cacheDir, "discussions"),
+		releasesPath: repoCacheDir ? join(repoCacheDir, "releases") : join(cacheDir, "releases"),
+		docsToIndex: []
+	};
+	await walkSteps(defaultTimelineSteps, ctx);
+	return {
+		docsToIndex: ctx.docsToIndex,
+		hasIssues: features.issues && existsSync(ctx.issuesDir),
+		hasDiscussions: features.discussions && existsSync(ctx.discussionsDir),
+		hasReleases: features.releases && existsSync(ctx.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, extraPackages, onIndexProgress } = opts;
+	const cache = createReferenceCache(packageName, version);
+	cache.linkInto(skillDir, cwd, resources.docsType, {
+		features,
+		repoInfo: resources.repoInfo,
+		extraPackages
+	});
+	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, selectLlmConfig as c, runSkillEnhancement as d, writeBaseSkill as f, findRelatedSkills as i, applyCachedSections as l, detectChangelog as n, DEFAULT_SECTIONS as o, writePromptFiles as p, fetchAndCacheResources as r, resolveAutoModel as s, buildSkillContext as t, enhanceSkillWithLLM as u };
+
+//# sourceMappingURL=pipeline.mjs.map