skilld 1.4.0 → 1.5.0

package/dist/_chunks/sync-shared2.mjs

@@ -0,0 +1,1054 @@
+import { a as getModelLabel, i as getAvailableModels, o as getModelName, r as createToolProgress, s as optimizeDocs } from "./agent.mjs";
+import { a as getRepoCacheDir, i as getPackageDbPath, o as getCacheDir } from "./config.mjs";
+import { n as sanitizeMarkdown } from "./sanitize.mjs";
+import { _ as resolvePkgDir, a as getShippedSkills, b as writeToRepoCache, c as linkCachedDir, d as linkRepoCachedDir, f as linkShippedSkill, h as readCachedDocs, l as linkPkg, m as listReferenceFiles, n as clearCache, o as hasShippedDocs, u as linkPkgNamed, y as writeToCache } from "./cache.mjs";
+import { i as parseFrontmatter } from "./markdown.mjs";
+import { SearchDepsUnavailableError, createIndex, listIndexIds } from "../retriv/index.mjs";
+import { a as semverDiff, c as getBlogPreset, n as getSharedSkillsDir, p as getPrereleaseChangelogRef } from "./shared.mjs";
+import { B as isGhAvailable, C as downloadLlmsDocs, D as normalizeLlmsLinks, F as formatDiscussionAsMarkdown, G as fetchReleaseNotes, H as toCrawlPattern, I as generateDiscussionIndex, K as generateReleaseIndex, L as fetchGitHubIssues, M as resolveEntryFiles, N as generateDocsIndex, P as fetchGitHubDiscussions, R as formatIssueAsMarkdown, T as fetchLlmsTxt, U as fetchBlogReleases, V as fetchCrawledDocs, Z as fetchGitHubRaw, b as isShallowGitDocs, h as fetchGitDocs, n as fetchNpmPackage, q as isPrerelease, tt as parseGitHubUrl, u as resolveLocalPackageDocs, v as fetchReadmeContent, y as filterFrameworkDocs, z as generateIssueIndex } from "./sources.mjs";
+import { a as targets } from "./detect.mjs";
+import { c as SECTION_OUTPUT_FILES, g as maxLines, h as maxItems, l as buildAllSectionPrompts, t as generateSkillMd } from "./prompts.mjs";
+import { D as registerProject, E as readConfig, S as defaultFeatures, f as pickModel, k as updateConfig, l as isInteractive, t as NO_MODELS_MESSAGE } from "./cli-helpers.mjs";
+import { i as readLock, n as parsePackages, s as writeLock } from "./lockfile.mjs";
+import { join, relative, resolve } from "pathe";
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import * as p from "@clack/prompts";
+//#region src/commands/sync-shared.ts
+/** Max docs sent to the embedding pipeline to prevent oversized indexes */
+const MAX_INDEX_DOCS = 250;
+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"
+};
+/** Classify a cached doc path into the right metadata type */
+function classifyCachedDoc(path) {
+	const issueMatch = path.match(/^issues\/issue-(\d+)\.md$/);
+	if (issueMatch) return {
+		type: "issue",
+		number: Number(issueMatch[1])
+	};
+	const discussionMatch = path.match(/^discussions\/discussion-(\d+)\.md$/);
+	if (discussionMatch) return {
+		type: "discussion",
+		number: Number(discussionMatch[1])
+	};
+	if (path.startsWith("releases/")) return { type: "release" };
+	return { type: "doc" };
+}
+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 = /* @__PURE__ */ new Map();
+	if (lock) for (const [dirName, info] of Object.entries(lock.skills)) {
+		if (info.packageName) pkgToDirName.set(info.packageName, dirName);
+		for (const pkg of parsePackages(info.packages)) pkgToDirName.set(pkg.name, dirName);
+	}
+	const installedSkills = readdirSync(skillsDir);
+	const installedSet = new Set(installedSkills);
+	for (const dep of deps) {
+		const dirName = pkgToDirName.get(dep);
+		if (dirName && installedSet.has(dirName)) related.push(dirName);
+	}
+	return related.slice(0, 5);
+}
+/** Clear cache + db for --force flag */
+function forceClearCache(packageName, version, repoInfo) {
+	clearCache(packageName, version);
+	const forcedDbPath = getPackageDbPath(packageName, version);
+	if (existsSync(forcedDbPath)) rmSync(forcedDbPath, {
+		recursive: true,
+		force: true
+	});
+	if (repoInfo) {
+		const repoDir = getRepoCacheDir(repoInfo.owner, repoInfo.repo);
+		if (existsSync(repoDir)) rmSync(repoDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/** Link all reference symlinks (pkg, docs, issues, discussions, releases) */
+function linkAllReferences(skillDir, packageName, cwd, version, docsType, extraPackages, features, repoInfo) {
+	const f = features ?? readConfig().features ?? defaultFeatures;
+	try {
+		linkPkg(skillDir, packageName, cwd, version);
+		linkPkgNamed(skillDir, packageName, cwd, version);
+		if (!hasShippedDocs(packageName, cwd, version) && docsType !== "readme") linkCachedDir(skillDir, packageName, version, "docs");
+		if (f.issues) if (repoInfo) linkRepoCachedDir(skillDir, repoInfo.owner, repoInfo.repo, "issues");
+		else linkCachedDir(skillDir, packageName, version, "issues");
+		if (f.discussions) if (repoInfo) linkRepoCachedDir(skillDir, repoInfo.owner, repoInfo.repo, "discussions");
+		else linkCachedDir(skillDir, packageName, version, "discussions");
+		if (f.releases) if (repoInfo) linkRepoCachedDir(skillDir, repoInfo.owner, repoInfo.repo, "releases");
+		else linkCachedDir(skillDir, packageName, version, "releases");
+		linkCachedDir(skillDir, packageName, version, "sections");
+		if (extraPackages) {
+			for (const pkg of extraPackages) if (pkg.name !== packageName) linkPkgNamed(skillDir, pkg.name, cwd, pkg.version);
+		}
+	} catch {}
+}
+/** Detect docs type from cached directory contents */
+function detectDocsType(packageName, version, repoUrl, llmsUrl) {
+	const cacheDir = getCacheDir(packageName, version);
+	if (existsSync(join(cacheDir, "docs", "index.md")) || existsSync(join(cacheDir, "docs", "guide"))) return {
+		docsType: "docs",
+		docSource: repoUrl ? `${repoUrl}/tree/v${version}/docs` : "git"
+	};
+	if (existsSync(join(cacheDir, "llms.txt"))) return {
+		docsType: "llms.txt",
+		docSource: llmsUrl || "llms.txt"
+	};
+	if (existsSync(join(cacheDir, "docs", "README.md"))) return { docsType: "readme" };
+	return { docsType: "readme" };
+}
+/** Link shipped skills, write lock entries, register project. Returns result or null if no shipped skills. */
+function handleShippedSkills(packageName, version, cwd, agent, global) {
+	const shippedSkills = getShippedSkills(packageName, cwd, version);
+	if (shippedSkills.length === 0) return null;
+	const baseDir = resolveBaseDir(cwd, agent, global);
+	mkdirSync(baseDir, { recursive: true });
+	for (const shipped of shippedSkills) {
+		linkShippedSkill(baseDir, shipped.skillName, shipped.skillDir);
+		writeLock(baseDir, shipped.skillName, {
+			packageName,
+			version,
+			source: "shipped",
+			syncedAt: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
+			generator: "skilld"
+		});
+	}
+	if (!global) registerProject(cwd);
+	return {
+		shipped: shippedSkills,
+		baseDir
+	};
+}
+/** Resolve the base skills directory for an agent */
+function resolveBaseDir(cwd, agent, global) {
+	if (global) return targets[agent].globalSkillsDir;
+	const shared = getSharedSkillsDir(cwd);
+	if (shared) return shared;
+	const agentConfig = targets[agent];
+	return join(cwd, agentConfig.skillsDir);
+}
+/** Try resolving a `link:` dependency to local package docs. Returns null if not a link dep or resolution fails. */
+async function resolveLocalDep(packageName, cwd) {
+	const pkgPath = join(cwd, "package.json");
+	if (!existsSync(pkgPath)) return null;
+	const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+	const depVersion = {
+		...pkg.dependencies,
+		...pkg.devDependencies
+	}[packageName];
+	if (!depVersion?.startsWith("link:")) return null;
+	return resolveLocalPackageDocs(resolve(cwd, depVersion.slice(5)));
+}
+/** Detect CHANGELOG.md in a package directory or cached releases */
+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;
+}
+/** Fetch and cache all resources for a package (docs cascade + issues + discussions + releases) */
+async function fetchAndCacheResources(opts) {
+	const { packageName, resolved, version, onProgress } = opts;
+	const features = opts.features ?? readConfig().features ?? defaultFeatures;
+	const cacheInvalidated = opts.useCache && resolved.crawlUrl && detectDocsType(packageName, version, 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 cachedDocs = [];
+		const isFrameworkDoc = (path) => filterFrameworkDocs([path], packageName).length > 0;
+		if (resolved.gitDocsUrl && resolved.repoUrl) {
+			const gh = parseGitHubUrl(resolved.repoUrl);
+			if (gh) {
+				onProgress("Fetching git docs");
+				const gitDocs = await fetchGitDocs(gh.owner, gh.repo, version, packageName);
+				if (gitDocs?.fallback) warnings.push(`Docs fetched from ${gitDocs.ref} branch (no tag found for v${version})`);
+				if (gitDocs && gitDocs.files.length > 0) {
+					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}`);
+							if (!content) return null;
+							return {
+								file,
+								content
+							};
+						}));
+						results.push(...batchResults);
+					}
+					for (const r of results) if (r) {
+						const stripped = gitDocs.docsPrefix ? r.file.replace(gitDocs.docsPrefix, "") : r.file;
+						const cachePath = stripped.startsWith("docs/") ? stripped : `docs/${stripped}`;
+						cachedDocs.push({
+							path: cachePath,
+							content: r.content
+						});
+						docsToIndex.push({
+							id: cachePath,
+							content: r.content,
+							metadata: {
+								package: packageName,
+								source: cachePath,
+								type: "doc"
+							}
+						});
+					}
+					const downloaded = results.filter(Boolean).length;
+					if (downloaded > 0) if (isShallowGitDocs(downloaded) && resolved.llmsUrl) {
+						onProgress(`Shallow git-docs (${downloaded} files), trying llms.txt`);
+						cachedDocs.length = 0;
+						docsToIndex.length = 0;
+					} else {
+						docSource = `${resolved.repoUrl}/tree/${gitDocs.ref}/docs`;
+						docsType = "docs";
+						writeToCache(packageName, version, cachedDocs);
+						if (resolved.llmsUrl) {
+							onProgress("Caching supplementary llms.txt");
+							const llmsContent = await fetchLlmsTxt(resolved.llmsUrl);
+							if (llmsContent) {
+								const baseUrl = resolved.docsUrl || new URL(resolved.llmsUrl).origin;
+								const supplementary = [{
+									path: "llms.txt",
+									content: normalizeLlmsLinks(llmsContent.raw, baseUrl)
+								}];
+								if (llmsContent.links.length > 0) {
+									onProgress(`Downloading ${llmsContent.links.length} supplementary docs`);
+									const docs = await downloadLlmsDocs(llmsContent, baseUrl, (url, done, total) => {
+										onProgress(`Downloading supplementary doc ${done + 1}/${total}`);
+									});
+									for (const doc of docs) {
+										if (!isFrameworkDoc(doc.url)) continue;
+										const localPath = doc.url.startsWith("/") ? doc.url.slice(1) : doc.url;
+										supplementary.push({
+											path: join("llms-docs", ...localPath.split("/")),
+											content: doc.content
+										});
+									}
+								}
+								writeToCache(packageName, version, supplementary);
+							}
+						}
+					}
+				}
+			}
+		}
+		if (resolved.crawlUrl && cachedDocs.length === 0) {
+			onProgress("Crawling website");
+			const crawledDocs = await fetchCrawledDocs(resolved.crawlUrl, onProgress).catch((err) => {
+				warnings.push(`Crawl failed for ${resolved.crawlUrl}: ${err?.message || err}`);
+				return [];
+			});
+			if (crawledDocs.length === 0 && resolved.crawlUrl) warnings.push(`Crawl returned 0 docs from ${resolved.crawlUrl}`);
+			if (crawledDocs.length > 0) {
+				for (const doc of crawledDocs) {
+					if (!isFrameworkDoc(doc.path)) continue;
+					cachedDocs.push(doc);
+					docsToIndex.push({
+						id: doc.path,
+						content: doc.content,
+						metadata: {
+							package: packageName,
+							source: doc.path,
+							type: "doc"
+						}
+					});
+				}
+				docSource = resolved.crawlUrl;
+				docsType = "docs";
+				writeToCache(packageName, version, cachedDocs);
+			}
+		}
+		if (resolved.llmsUrl && cachedDocs.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;
+				cachedDocs.push({
+					path: "llms.txt",
+					content: normalizeLlmsLinks(llmsContent.raw, baseUrl)
+				});
+				if (llmsContent.links.length > 0) {
+					onProgress(`Downloading ${llmsContent.links.length} linked docs`);
+					const docs = await downloadLlmsDocs(llmsContent, baseUrl, (url, done, total) => {
+						onProgress(`Downloading linked doc ${done + 1}/${total}`);
+					});
+					for (const doc of docs) {
+						if (!isFrameworkDoc(doc.url)) continue;
+						const cachePath = join("docs", ...(doc.url.startsWith("/") ? doc.url.slice(1) : doc.url).split("/"));
+						cachedDocs.push({
+							path: cachePath,
+							content: doc.content
+						});
+						docsToIndex.push({
+							id: doc.url,
+							content: doc.content,
+							metadata: {
+								package: packageName,
+								source: cachePath,
+								type: "doc"
+							}
+						});
+					}
+					if (docs.length > 0) docsType = "docs";
+				}
+				writeToCache(packageName, version, cachedDocs);
+			}
+		}
+		if (resolved.docsUrl && !cachedDocs.some((d) => d.path.startsWith("docs/"))) {
+			const crawlPattern = resolved.crawlUrl || toCrawlPattern(resolved.docsUrl);
+			onProgress("Crawling docs site");
+			const crawledDocs = await fetchCrawledDocs(crawlPattern, onProgress, resolved.crawlUrl ? 200 : 400).catch((err) => {
+				warnings.push(`Crawl failed for ${crawlPattern}: ${err?.message || err}`);
+				return [];
+			});
+			if (crawledDocs.length > 0) {
+				for (const doc of crawledDocs) {
+					if (!isFrameworkDoc(doc.path)) continue;
+					cachedDocs.push(doc);
+					docsToIndex.push({
+						id: doc.path,
+						content: doc.content,
+						metadata: {
+							package: packageName,
+							source: doc.path,
+							type: "doc"
+						}
+					});
+				}
+				docSource = crawlPattern;
+				docsType = "docs";
+				writeToCache(packageName, version, cachedDocs);
+			}
+		}
+		if (resolved.readmeUrl && cachedDocs.length === 0) {
+			onProgress("Fetching README");
+			const content = await fetchReadmeContent(resolved.readmeUrl);
+			if (content) {
+				cachedDocs.push({
+					path: "docs/README.md",
+					content
+				});
+				docsToIndex.push({
+					id: "README.md",
+					content,
+					metadata: {
+						package: packageName,
+						source: "docs/README.md",
+						type: "doc"
+					}
+				});
+				writeToCache(packageName, version, cachedDocs);
+			}
+		}
+		if (docsType !== "readme" && cachedDocs.filter((d) => d.path.startsWith("docs/") && d.path.endsWith(".md")).length > 1) {
+			const docsIndex = generateDocsIndex(cachedDocs);
+			if (docsIndex) writeToCache(packageName, version, [{
+				path: "docs/_INDEX.md",
+				content: docsIndex
+			}]);
+		}
+	} else {
+		onProgress("Loading cached docs");
+		const detected = detectDocsType(packageName, version, resolved.repoUrl, resolved.llmsUrl);
+		docsType = detected.docsType;
+		if (detected.docSource) docSource = detected.docSource;
+		if (!existsSync(getPackageDbPath(packageName, version))) {
+			onProgress("Reading cached docs for indexing");
+			const cached = readCachedDocs(packageName, version);
+			for (const doc of cached) docsToIndex.push({
+				id: doc.path,
+				content: doc.content,
+				metadata: {
+					package: packageName,
+					source: doc.path,
+					...classifyCachedDoc(doc.path)
+				}
+			});
+		}
+		if (docsType !== "readme" && !existsSync(join(getCacheDir(packageName, version), "docs", "_INDEX.md"))) {
+			onProgress("Generating docs index");
+			const cached = readCachedDocs(packageName, version);
+			if (cached.filter((d) => d.path.startsWith("docs/") && d.path.endsWith(".md")).length > 1) {
+				const docsIndex = generateDocsIndex(cached);
+				if (docsIndex) writeToCache(packageName, version, [{
+					path: "docs/_INDEX.md",
+					content: docsIndex
+				}]);
+			}
+		}
+	}
+	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, opts.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, opts.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, opts.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 {
+		docSource,
+		docsType,
+		docsToIndex,
+		hasIssues: features.issues && existsSync(issuesDir),
+		hasDiscussions: features.discussions && existsSync(discussionsDir),
+		hasReleases: features.releases && existsSync(releasesPath),
+		warnings,
+		repoInfo,
+		usedCache: useCache
+	};
+}
+/**
+* Extract the parent document ID from a chunk ID.
+* Chunk IDs have the form "docId#chunk-N"; non-chunk IDs return as-is.
+*/
+function parentDocId(id) {
+	const idx = id.indexOf("#chunk-");
+	return idx === -1 ? id : id.slice(0, idx);
+}
+/** Cap and sort docs by type priority, mutates and truncates allDocs in place */
+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;
+}
+/** Index all resources into the search database, with incremental support */
+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, MAX_INDEX_DOCS, 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;
+	}
+}
+/**
+* Eject references: copy cached files as real files into references/ dir.
+* Used for portable skills (git repos, sharing). Replaces symlinks with copies.
+* Does NOT copy pkg files — those reference node_modules directly.
+*/
+function ejectReferences(skillDir, packageName, cwd, version, docsType, features, repoInfo) {
+	const f = features ?? readConfig().features ?? defaultFeatures;
+	const cacheDir = getCacheDir(packageName, version);
+	const refsDir = join(skillDir, "references");
+	const repoDir = repoInfo ? getRepoCacheDir(repoInfo.owner, repoInfo.repo) : cacheDir;
+	if (!hasShippedDocs(packageName, cwd, version) && docsType !== "readme") copyCachedSubdir(cacheDir, refsDir, "docs");
+	if (f.issues) copyCachedSubdir(repoDir, refsDir, "issues");
+	if (f.discussions) copyCachedSubdir(repoDir, refsDir, "discussions");
+	if (f.releases) copyCachedSubdir(repoDir, refsDir, "releases");
+}
+/** Recursively copy a cached subdirectory into the references dir */
+function copyCachedSubdir(cacheDir, refsDir, subdir) {
+	const srcDir = join(cacheDir, subdir);
+	if (!existsSync(srcDir)) return;
+	const destDir = join(refsDir, subdir);
+	mkdirSync(destDir, { recursive: true });
+	function walk(dir, rel) {
+		for (const entry of readdirSync(dir, { withFileTypes: true })) {
+			const srcPath = join(dir, entry.name);
+			const destPath = join(destDir, rel ? `${rel}/${entry.name}` : entry.name);
+			if (entry.isDirectory()) {
+				mkdirSync(destPath, { recursive: true });
+				walk(srcPath, rel ? `${rel}/${entry.name}` : entry.name);
+			} else copyFileSync(srcPath, destPath);
+		}
+	}
+	walk(srcDir, "");
+}
+/**
+* Check if .gitignore has `.skilld` entry.
+* If missing, prompt to add it. Skipped for global installs.
+*/
+async function ensureGitignore(skillsDir, cwd, isGlobal) {
+	if (isGlobal) return;
+	const gitignorePath = join(cwd, ".gitignore");
+	const pattern = ".skilld";
+	if (existsSync(gitignorePath)) {
+		if (readFileSync(gitignorePath, "utf-8").split("\n").some((line) => line.trim() === pattern)) return;
+	}
+	if (!isInteractive()) {
+		const entry = `\n# Skilld references (recreated by \`skilld install\`)\n${pattern}\n`;
+		if (existsSync(gitignorePath)) appendFileSync(gitignorePath, `${readFileSync(gitignorePath, "utf-8").endsWith("\n") ? "" : "\n"}${entry}`);
+		else writeFileSync(gitignorePath, entry);
+		return;
+	}
+	const relSkillsDir = relative(cwd, skillsDir) || ".";
+	p.log.info(`\x1B[1mGit guidance:\x1B[0m\n  \x1B[32m✓\x1B[0m Commit: \x1B[36m${relSkillsDir}/*/SKILL.md\x1B[0m\n  \x1B[32m✓\x1B[0m Commit: \x1B[36m${relSkillsDir}/skilld-lock.yaml\x1B[0m\n  \x1B[31m✗\x1B[0m Ignore: \x1B[36m${pattern}\x1B[0m \x1B[90m(recreated by \`skilld install\`)\x1B[0m`);
+	const add = await p.confirm({
+		message: `Add \`${pattern}\` to .gitignore?`,
+		initialValue: true
+	});
+	if (p.isCancel(add) || !add) return;
+	const entry = `\n# Skilld references (recreated by \`skilld install\`)\n${pattern}\n`;
+	if (existsSync(gitignorePath)) appendFileSync(gitignorePath, `${readFileSync(gitignorePath, "utf-8").endsWith("\n") ? "" : "\n"}${entry}`);
+	else writeFileSync(gitignorePath, entry);
+	p.log.success("Updated .gitignore");
+}
+const SKILLD_MARKER_START = "<!-- skilld -->";
+const SKILLD_MARKER_END = "<!-- /skilld -->";
+const DEFAULT_SKILL_HINT = "Before modifying code, evaluate each installed skill against the current task.\nFor each skill, determine YES/NO relevance and invoke all YES skills before proceeding.";
+function getSkillInstructions(agent) {
+	return `${SKILLD_MARKER_START}\n${targets[agent].skillActivationHint || DEFAULT_SKILL_HINT}\n${SKILLD_MARKER_END}`;
+}
+function getMdcSkillInstructions(agent) {
+	return `---\ndescription: "Activates installed skilld skills before code changes"\nalwaysApply: true\n---\n\n${targets[agent].skillActivationHint || DEFAULT_SKILL_HINT}`;
+}
+/**
+* Check if agent instruction file has skilld skill-activation snippet.
+* If missing, prompt to add it. Skipped for global installs or agents without an instructionFile.
+*/
+async function ensureAgentInstructions(agent, cwd, isGlobal) {
+	if (isGlobal) return;
+	const agentConfig = targets[agent];
+	if (!agentConfig.instructionFile) return;
+	const filePath = join(cwd, agentConfig.instructionFile);
+	if (agentConfig.instructionFile.endsWith(".mdc")) {
+		if (existsSync(filePath)) return;
+		const content = `${getMdcSkillInstructions(agent)}\n`;
+		if (!isInteractive()) {
+			mkdirSync(join(filePath, ".."), { recursive: true });
+			writeFileSync(filePath, content);
+			return;
+		}
+		p.note(`This tells your agent to check installed skills before making
+code changes. Without it, skills are available but may not
+activate automatically.
+
+\x1B[90m${getMdcSkillInstructions(agent)}\x1B[0m`, `Create ${agentConfig.instructionFile}`);
+		const add = await p.confirm({
+			message: `Create ${agentConfig.instructionFile} with skill activation instructions?`,
+			initialValue: true
+		});
+		if (p.isCancel(add) || !add) return;
+		mkdirSync(join(filePath, ".."), { recursive: true });
+		writeFileSync(filePath, content);
+		p.log.success(`Created ${agentConfig.instructionFile}`);
+		return;
+	}
+	if (existsSync(filePath)) {
+		if (readFileSync(filePath, "utf-8").includes("<!-- skilld -->")) return;
+	}
+	if (!isInteractive()) {
+		if (existsSync(filePath)) appendFileSync(filePath, `${readFileSync(filePath, "utf-8").endsWith("\n") ? "" : "\n"}\n${getSkillInstructions(agent)}\n`);
+		else writeFileSync(filePath, `${getSkillInstructions(agent)}\n`);
+		return;
+	}
+	const action = existsSync(filePath) ? "Append to" : "Create";
+	p.note(`This tells your agent to check installed skills before making
+code changes. Without it, skills are available but may not
+activate automatically.
+
+\x1B[90m${getSkillInstructions(agent).replace(/\n/g, "\n")}\x1B[0m`, `${action} ${agentConfig.instructionFile}`);
+	const add = await p.confirm({
+		message: `${action} ${agentConfig.instructionFile} with skill activation instructions?`,
+		initialValue: true
+	});
+	if (p.isCancel(add) || !add) return;
+	if (existsSync(filePath)) appendFileSync(filePath, `${readFileSync(filePath, "utf-8").endsWith("\n") ? "" : "\n"}\n${getSkillInstructions(agent)}\n`);
+	else writeFileSync(filePath, `${getSkillInstructions(agent)}\n`);
+	p.log.success(`Updated ${agentConfig.instructionFile}`);
+}
+/** Default sections when model is pre-set (non-interactive) */
+const DEFAULT_SECTIONS = ["best-practices", "api-changes"];
+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
+	};
+}
+/**
+* Resolve sections + model for LLM enhancement.
+* If presetModel is provided, uses DEFAULT_SECTIONS without prompting.
+* Returns null if cancelled or no sections/model selected.
+*/
+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 = "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
+	};
+}
+async function enhanceSkillWithLLM(opts) {
+	const { packageName, version, skillDir, dirName, model, resolved, relatedSkills, hasIssues, hasDiscussions, hasReleases, hasChangelog, docsType, hasShippedDocs: shippedDocs, pkgFiles, force, debug, sections, customPrompt, packages, features, eject, overheadLines } = opts;
+	const effectiveFeatures = features;
+	const llmLog = p.taskLog({ title: `Agent exploring ${packageName}` });
+	const docFiles = listReferenceFiles(skillDir);
+	const { optimized, wasOptimized, usage, cost, warnings, error, debugLogsDir } = await optimizeDocs({
+		packageName,
+		skillDir,
+		model,
+		version,
+		hasGithub: hasIssues || hasDiscussions,
+		hasReleases,
+		hasChangelog,
+		docFiles,
+		docsType,
+		hasShippedDocs: shippedDocs,
+		noCache: force,
+		debug,
+		sections,
+		customPrompt,
+		features: effectiveFeatures,
+		pkgFiles,
+		overheadLines,
+		onProgress: 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`);
+		const skillMd = generateSkillMd({
+			name: packageName,
+			version,
+			releasedAt: resolved.releasedAt,
+			distTags: resolved.distTags,
+			body: optimized,
+			relatedSkills,
+			hasIssues,
+			hasDiscussions,
+			hasReleases,
+			hasChangelog,
+			docsType,
+			hasShippedDocs: shippedDocs,
+			pkgFiles,
+			generatedBy: getModelLabel(model),
+			dirName,
+			packages,
+			repoUrl: resolved.repoUrl,
+			features,
+			eject
+		});
+		writeFileSync(join(skillDir, "SKILL.md"), skillMd);
+	} else llmLog.error(`Enhancement failed${error ? `: ${error}` : ""}`);
+}
+/**
+* Build and write PROMPT_*.md files for manual LLM use.
+* Returns the list of sections that had prompts written.
+*/
+function writePromptFiles(opts) {
+	const { skillDir, sections, customPrompt, features } = opts;
+	const docFiles = listReferenceFiles(skillDir);
+	const prompts = buildAllSectionPrompts({
+		packageName: opts.packageName,
+		skillDir,
+		version: opts.version,
+		hasIssues: opts.hasIssues,
+		hasDiscussions: opts.hasDiscussions,
+		hasReleases: opts.hasReleases,
+		hasChangelog: opts.hasChangelog,
+		docFiles,
+		docsType: opts.docsType,
+		hasShippedDocs: opts.hasShippedDocs,
+		pkgFiles: opts.pkgFiles,
+		customPrompt,
+		features,
+		overheadLines: opts.overheadLines,
+		sections
+	});
+	const skilldDir = join(skillDir, ".skilld");
+	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;
+}
+//#endregion
+export { writePromptFiles as S, linkAllReferences as _, classifyCachedDoc as a, selectLlmConfig as b, ejectReferences as c, ensureGitignore as d, fetchAndCacheResources as f, indexResources as g, handleShippedSkills as h, SKILLD_MARKER_START as i, enhanceSkillWithLLM as l, forceClearCache as m, RESOLVE_STEP_LABELS as n, detectChangelog as o, findRelatedSkills as p, SKILLD_MARKER_END as r, detectDocsType as s, DEFAULT_SECTIONS as t, ensureAgentInstructions as u, resolveBaseDir as v, selectSkillSections as x, resolveLocalDep as y };
+
+//# sourceMappingURL=sync-shared2.mjs.map