skilld 0.9.6 → 0.10.0

package/dist/_chunks/detect-imports.mjs

@@ -611,7 +611,15 @@ function apiChangesSection({ packageName, version, hasReleases, hasChangelog, ha
 		useFor: "Skip unless searching a specific removed API"
 	});
 	const releaseGuidance = hasReleases ? `\n\n**Scan release history:** Read \`./.skilld/releases/_INDEX.md\` for a timeline. Focus on [MAJOR] and [MINOR] releases — these contain breaking changes and renamed/deprecated APIs that LLMs trained on older data will get wrong.` : "";
-	const versionGuidance = major && minor ? `\n\n**New APIs in recent releases are the highest-priority gaps** — the LLM was trained on older data and will use outdated or non-existent APIs instead. Search for recent version tags and "Features" in releases/changelog to find new composables, components, hooks, or utilities added in recent major/minor versions.` : "";
+	const versionGuidance = major && minor ? `\n\n**Item scoring** — include only items scoring ≥ 3:
+
+| Change type | v${major}.x | v${Number(major) - 1}.x | Older |
+|-------------|:---:|:---:|:---:|
+| Silent breakage (compiles, wrong result) | 5 | 4 | 2 |
+| Removed/breaking API | 5 | 3 | 0 |
+| New API unknown to LLMs | 4 | 1 | 0 |
+| Deprecated (still works) | 3 | 1 | 0 |
+| Renamed/moved | 3 | 1 | 0 |` : "";
 	return {
 		referenceWeights,
 		task: `**Find new, deprecated, and renamed APIs from version history.** Focus exclusively on APIs that changed between versions — LLMs trained on older data will use the wrong names, wrong signatures, or non-existent functions.
@@ -622,26 +630,24 @@ Find from releases/changelog:
 - **Signature changes** where old code compiles but behaves wrong (changed parameter order, return types, default values)
 - **Breaking changes** in recent versions (v2 → v3 migrations, major version bumps)
 ${searchHints.length ? `\nSearch: ${searchHints.join(", ")}` : ""}${releaseGuidance}${versionGuidance}`,
-		format: `## API Changes
+		format: `<format-example note="Illustrative structure only — replace placeholder names with real ${packageName} APIs">
+## API Changes
 
 This section documents version-specific API changes — prioritize recent major/minor releases.
 
-\`\`\`
-## API Changes
-
-⚠️ \`createClient(url, key)\` — v2 changed to \`createClient({ url, key })\`, old positional args silently ignored [source](./.skilld/releases/v2.0.0.md)
+- BREAKING: \`createClient(url, key)\` — v2 changed to \`createClient({ url, key })\`, old positional args silently ignored [source](./.skilld/releases/v2.0.0.md)
 
-✨ \`useTemplateRef()\` — new in v3.5, replaces \`$refs\` pattern [source](./.skilld/releases/v3.5.0.md)
+- NEW: \`useTemplateRef()\` — new in v3.5, replaces \`$refs\` pattern [source](./.skilld/releases/v3.5.0.md)
 
-⚠️ \`db.query()\` — returns \`{ rows }\` not raw array since v4 [source](./.skilld/docs/migration.md)
-\`\`\`
+- BREAKING: \`db.query()\` — returns \`{ rows }\` not raw array since v4 [source](./.skilld/docs/migration.md)
+</format-example>
 
-Each item: ⚠️ (breaking/deprecated) or ✨ (new) + API name + what changed + source link.`,
+Each item: BREAKING/DEPRECATED/NEW label + API name + what changed + source link. All source links MUST use \`./.skilld/\` prefix (e.g., \`[source](./.skilld/releases/v2.0.0.md)\`). Do NOT use emoji — use plain text markers only.`,
 		rules: [
 			`- **API Changes:** ${maxItems(6, 12, enabledSectionCount)} items from version history, MAX ${maxLines(50, 80, enabledSectionCount)} lines`,
 			"- Prioritize recent major/minor releases over old patch versions",
 			"- Focus on APIs that CHANGED, not general conventions or gotchas",
-			"- New APIs get ✨, deprecated/breaking get ⚠️",
+			"- New APIs get NEW: prefix, deprecated/breaking get BREAKING: or DEPRECATED: prefix",
 			hasReleases ? "- Start with `./.skilld/releases/_INDEX.md` to identify recent major/minor releases, then read specific release files" : "",
 			hasChangelog ? "- Scan CHANGELOG.md for version headings, focus on Features/Breaking Changes sections" : ""
 		].filter(Boolean)
@@ -660,14 +666,14 @@ function bestPracticesSection({ packageName, hasIssues, hasDiscussions, hasRelea
 	if (hasDiscussions) referenceWeights.push({
 		name: "Discussions",
 		path: "./.skilld/discussions/_INDEX.md",
-		score: 8,
-		useFor: "Q&A with accepted answers reveal \"the right way\""
+		score: 5,
+		useFor: "Only maintainer-confirmed patterns — community workarounds are lower confidence"
 	});
 	if (hasIssues) referenceWeights.push({
 		name: "Issues",
 		path: "./.skilld/issues/_INDEX.md",
-		score: 7,
-		useFor: "Questions reveal what users find confusing"
+		score: 4,
+		useFor: "Only workarounds confirmed by maintainers or with broad adoption"
 	});
 	if (hasReleases) referenceWeights.push({
 		name: "Releases",
@@ -683,33 +689,38 @@ function bestPracticesSection({ packageName, hasIssues, hasDiscussions, hasRelea
 	});
 	return {
 		referenceWeights,
-		task: `**Extract non-obvious best practices from the references.** Focus on recommended patterns Claude wouldn't already know: idiomatic usage, preferred configurations, performance tips, patterns that differ from what a developer would assume. Surface new patterns from recent minor releases that may post-date training data. Every item must link to a verified source file.
+		task: `**Extract non-obvious best practices from the references.** Focus on recommended patterns the LLM wouldn't already know: idiomatic usage, preferred configurations, performance tips, patterns that differ from what a developer would assume. Surface new patterns from recent minor releases that may post-date training data.
 
-Skip: obvious API usage, installation steps, general TypeScript/programming patterns, anything a developer would naturally write without reading the docs.
+Skip: obvious API usage, installation steps, general TypeScript/programming patterns not specific to this package, anything a developer would naturally write without reading the docs. Every item must be specific to ${packageName} — reject general programming advice that applies to any project.
 ${searchHints.length ? `\nSearch: ${searchHints.join(", ")}` : ""}`,
-		format: `\`\`\`
+		format: `<format-example note="Illustrative structure only — replace placeholder names with real ${packageName} APIs">
+\`\`\`
 ## Best Practices
 
-✅ Pass \`AbortSignal\` to long-lived operations — enables caller-controlled cancellation [source](./.skilld/docs/api.md)
+- Use ${packageName}'s built-in \`createX()\` helper over manual wiring — handles cleanup and edge cases automatically [source](./.skilld/docs/api.md)
 
 \`\`\`ts
-async function fetchUser(id: string, signal?: AbortSignal) {
-  return fetch(\`/api/users/\${id}\`, { signal })
-}
-\`\`\`
+// Preferred
+const instance = createX({ ... })
 
-✅ Use \`satisfies\` for config objects — preserves literal types while validating shape [source](./.skilld/docs/config.md)
+// Avoid — misses cleanup, error boundaries
+const instance = new X()
+instance.init({ ... })
+\`\`\`
 
-✅ Prefer \`structuredClone()\` over spread for deep copies — handles nested objects, Maps, Sets [source](./.skilld/docs/utilities.md)
+- Pass config through \`defineConfig()\` — enables type inference and plugin merging [source](./.skilld/docs/config.md)
 
-✅ Set \`isolatedDeclarations: true\` — enables parallel .d.ts emit without full type-checking [source](./.skilld/docs/typescript.md)
+- Prefer \`useComposable()\` over direct imports in reactive contexts — ensures proper lifecycle binding [source](./.skilld/docs/composables.md)
 \`\`\`
+</format-example>
 
-Each item: ✅ + pattern name + why it's preferred + source link. Code block only when the pattern isn't obvious from the title. Use the most relevant language tag (ts, vue, css, json, etc).`,
+Each item: markdown list item (-) + ${packageName}-specific pattern + why it's preferred + source link. Code block only when the pattern isn't obvious from the title. Use the most relevant language tag (ts, vue, css, json, etc). Every example must be specific to ${packageName} — never generic TypeScript/JS advice. All source links MUST use \`./.skilld/\` prefix (e.g., \`[source](./.skilld/docs/guide.md)\`). Do NOT use emoji — use plain text markers only.`,
 		rules: [
 			`- **${maxItems(4, 10, enabledSectionCount)} best practice items**`,
 			`- **MAX ${maxLines(80, 150, enabledSectionCount)} lines** for best practices section`,
-			"- **Only link files confirmed to exist** via Glob or Read — no guessed paths"
+			"- **Verify before including:** Confirm file paths exist via Glob/Read before linking. Confirm functions/composables are real exports in `./.skilld/pkg/` `.d.ts` files before documenting",
+			"- **Diversity:** Cover at least 3 distinct areas of the library. No single feature should have more than 40% of items",
+			"- **Experimental APIs:** Mark unstable/experimental features with `(experimental)` in the description. Prioritize stable patterns"
 		]
 	};
 }
@@ -814,8 +825,11 @@ function formatDocTree(files) {
 	}
 	return [...dirs.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([dir, count]) => `- \`${dir}/\` (${count} .md files)`).join("\n");
 }
-function generateImportantBlock({ packageName, hasIssues, hasDiscussions, hasReleases, hasChangelog, docsType, hasShippedDocs, skillDir, features }) {
-	const rows = [["Docs", hasShippedDocs ? `\`${skillDir}/.skilld/pkg/docs/\` or \`${skillDir}/.skilld/pkg/README.md\`` : docsType === "llms.txt" ? `\`${skillDir}/.skilld/docs/llms.txt\`` : docsType === "readme" ? `\`${skillDir}/.skilld/pkg/README.md\`` : `\`${skillDir}/.skilld/docs/\``], ["Package", `\`${skillDir}/.skilld/pkg/\``]];
+function generateImportantBlock({ packageName, hasIssues, hasDiscussions, hasReleases, hasChangelog, docsType, hasShippedDocs, skillDir, features, pkgFiles }) {
+	const docsPath = hasShippedDocs ? `\`${skillDir}/.skilld/pkg/docs/\` or \`${skillDir}/.skilld/pkg/README.md\`` : docsType === "llms.txt" ? `\`${skillDir}/.skilld/docs/llms.txt\`` : docsType === "readme" ? `\`${skillDir}/.skilld/pkg/README.md\`` : `\`${skillDir}/.skilld/docs/\``;
+	const typesFile = pkgFiles?.find((f) => f.endsWith(".d.ts"));
+	const rows = [["Docs", docsPath], ["Package", `\`${skillDir}/.skilld/pkg/\``]];
+	if (typesFile) rows.push(["Types", `\`${skillDir}/.skilld/pkg/${typesFile}\` — **read this file directly** to verify exports`]);
 	if (hasIssues) rows.push(["Issues", `\`${skillDir}/.skilld/issues/\``]);
 	if (hasDiscussions) rows.push(["Discussions", `\`${skillDir}/.skilld/discussions/\``]);
 	if (hasChangelog) rows.push(["Changelog", `\`${skillDir}/.skilld/${hasChangelog}\``]);
@@ -858,18 +872,10 @@ ${generateImportantBlock({
 		docsType,
 		hasShippedDocs,
 		skillDir,
-		features: opts.features
+		features: opts.features,
+		pkgFiles: opts.pkgFiles
 	})}
-${docsSection ? `${docsSection}\n` : ""}
-
-## Skill Quality Principles
-
-The context window is a shared resource. Skills share it with system prompt, conversation history, other skills, and the user request.
-
-- **Only add what Claude doesn't know.** Claude already knows general programming, popular APIs, common patterns. Challenge every line: "Does this justify its token cost?"
-- **Prefer concise examples over verbose explanations.** A 2-line code example beats a paragraph.
-- **Skip:** API signatures, installation steps, tutorials, marketing, general programming knowledge, anything in the package README that's obvious
-- **Include:** Non-obvious gotchas, surprising defaults, version-specific breaking changes, pitfalls from issues, patterns that differ from what Claude would assume`;
+${docsSection ? `${docsSection}\n` : ""}`;
 }
 function getSectionDef(section, ctx, customPrompt) {
 	switch (section) {
@@ -902,14 +908,14 @@ function buildSectionPrompt(opts) {
 	const packageRules = getPackageRules(packageName);
 	const rules = [
 		...sectionDef.rules ?? [],
-		"- Link to exact source file where you found info",
-		"- TypeScript only",
 		...packageRules.map((r) => `- ${r}`),
-		"- Imperative voice (\"Use X\" not \"You should use X\")",
 		`- **NEVER fetch external URLs.** All information is in the local \`./.skilld/\` directory. Use Read, Glob${opts.features?.search !== false ? ", and `skilld search`" : ""} only.`,
 		"- **Do NOT use Task tool or spawn subagents.** Work directly.",
 		"- **Do NOT re-read files** you have already read in this session.",
-		"- **Read `_INDEX.md` first** in issues/releases/discussions — only drill into files that look relevant. Skip stub/placeholder files."
+		"- **Read `_INDEX.md` first** in issues/releases/discussions — only drill into files that look relevant. Skip stub/placeholder files.",
+		"- **Skip files starting with `PROMPT_`** — these are generation prompts, not reference material.",
+		"- **Stop exploring once you have enough high-quality items** to fill the budget. Do not read additional files just to be thorough.",
+		"- **To verify API exports:** Read the `.d.ts` file directly (see Types row in references). Do NOT use search with relative paths or `include` filters on package directories — they may silently return no results."
 	];
 	return `${preamble}${sectionDef.referenceWeights?.length ? `\n\n## Reference Priority\n\n| Reference | Path | Score | Use For |\n|-----------|------|:-----:|--------|\n${sectionDef.referenceWeights.map((w) => `| ${w.name} | [\`${w.path.split("/").pop()}\`](${w.path}) | ${w.score}/10 | ${w.useFor} |`).join("\n")}` : ""}
 
@@ -1004,23 +1010,28 @@ function unlinkSkillFromAgents(skillName, cwd) {
 function generateSkillMd(opts) {
 	const header = generatePackageHeader(opts);
 	const search = !opts.eject && opts.features?.search !== false ? generateSearchBlock(opts.name, opts.hasIssues, opts.hasReleases) : "";
-	const content = opts.body ? search ? `${header}\n\n${search}\n\n${opts.body}` : `${header}\n\n${opts.body}` : search ? `${header}\n\n${search}` : header;
+	const body = opts.body && opts.eject ? opts.body.replace(/\.\/\.skilld\//g, "./references/") : opts.body;
+	const content = body ? search ? `${header}\n\n${search}\n\n${body}` : `${header}\n\n${body}` : search ? `${header}\n\n${search}` : header;
 	const footer = generateFooter(opts.relatedSkills);
 	return sanitizeMarkdown(repairMarkdown(`${generateFrontmatter(opts)}${content}\n${footer}`));
 }
-function formatRelativeDate(isoDate) {
+function formatShortDate(isoDate) {
 	const date = new Date(isoDate);
-	const diffMs = (/* @__PURE__ */ new Date()).getTime() - date.getTime();
-	const diffDays = Math.floor(diffMs / (1e3 * 60 * 60 * 24));
-	if (diffDays === 0) return "today";
-	if (diffDays === 1) return "yesterday";
-	if (diffDays < 7) return `${diffDays} day${diffDays === 1 ? "" : "s"} ago`;
-	const weeks = Math.floor(diffDays / 7);
-	if (diffDays < 30) return `${weeks} week${weeks === 1 ? "" : "s"} ago`;
-	const months = Math.floor(diffDays / 30);
-	if (diffDays < 365) return `${months} month${months === 1 ? "" : "s"} ago`;
-	const years = Math.floor(diffDays / 365);
-	return `${years} year${years === 1 ? "" : "s"} ago`;
+	if (Number.isNaN(date.getTime())) return "";
+	return `${[
+		"Jan",
+		"Feb",
+		"Mar",
+		"Apr",
+		"May",
+		"Jun",
+		"Jul",
+		"Aug",
+		"Sep",
+		"Oct",
+		"Nov",
+		"Dec"
+	][date.getUTCMonth()]} ${date.getUTCFullYear()}`;
 }
 function generatePackageHeader({ name, description, version, releasedAt, dependencies, distTags, repoUrl, hasIssues, hasDiscussions, hasReleases, pkgFiles, packages, eject }) {
 	let title = `# ${name}`;
@@ -1031,8 +1042,8 @@ function generatePackageHeader({ name, description, version, releasedAt, depende
 	const lines = [title];
 	if (description) lines.push("", `> ${description}`);
 	if (version) {
-		const relativeDate = releasedAt ? formatRelativeDate(releasedAt) : "";
-		const versionStr = relativeDate ? `${version} (${relativeDate})` : version;
+		const dateStr = releasedAt ? formatShortDate(releasedAt) : "";
+		const versionStr = dateStr ? `${version} (${dateStr})` : version;
 		lines.push("", `**Version:** ${versionStr}`);
 	}
 	if (dependencies && Object.keys(dependencies).length > 0) {
@@ -1041,7 +1052,7 @@ function generatePackageHeader({ name, description, version, releasedAt, depende
 	}
 	if (distTags && Object.keys(distTags).length > 0) {
 		const tags = Object.entries(distTags).map(([tag, info]) => {
-			const relDate = info.releasedAt ? ` (${formatRelativeDate(info.releasedAt)})` : "";
+			const relDate = info.releasedAt ? ` (${formatShortDate(info.releasedAt)})` : "";
 			return `${tag}: ${info.version}${relDate}`;
 		}).join(", ");
 		lines.push(`**Tags:** ${tags}`);
@@ -1360,11 +1371,17 @@ function parseLine(line) {
 		if (obj.type === "message" && obj.role === "assistant" && obj.content) return obj.delta ? { textDelta: obj.content } : { fullText: obj.content };
 		if (obj.type === "tool_use" || obj.type === "tool_call") {
 			const name = obj.tool_name || obj.name || obj.tool || "tool";
-			if (name === "write_file" && obj.args?.content) return {
+			const params = obj.parameters || obj.args || obj.input || {};
+			const hint = params.file_path || params.path || params.dir_path || params.pattern || params.query || params.command || "";
+			if (name === "write_file" && params.content) return {
 				toolName: name,
-				writeContent: obj.args.content
+				toolHint: hint || void 0,
+				writeContent: params.content
+			};
+			return {
+				toolName: name,
+				toolHint: hint || void 0
 			};
-			return { toolName: name };
 		}
 		if (obj.type === "result") {
 			const s = obj.stats;
@@ -1647,7 +1664,7 @@ function optimizeSection(opts) {
 	});
 }
 async function optimizeDocs(opts) {
-	const { packageName, skillDir, model = "sonnet", version, hasGithub, hasReleases, hasChangelog, docFiles, docsType, hasShippedDocs, onProgress, timeout = 18e4, debug, noCache, sections, customPrompt, features } = opts;
+	const { packageName, skillDir, model = "sonnet", version, hasGithub, hasReleases, hasChangelog, docFiles, docsType, hasShippedDocs, onProgress, timeout = 18e4, debug, noCache, sections, customPrompt, features, pkgFiles } = opts;
 	const sectionPrompts = buildAllSectionPrompts({
 		packageName,
 		skillDir,
@@ -1661,6 +1678,7 @@ async function optimizeDocs(opts) {
 		hasShippedDocs,
 		customPrompt,
 		features,
+		pkgFiles,
 		sections: sections ?? [
 			"api-changes",
 			"best-practices",
@@ -1877,7 +1895,12 @@ function validateSectionOutput(content, section) {
 	return warnings;
 }
 function cleanSectionOutput(content) {
-	let cleaned = content.replace(/^```markdown\n?/m, "").replace(/\n?```$/m, "").trim();
+	let cleaned = content.trim();
+	const wrapMatch = cleaned.match(/^```(?:markdown|md)?[^\S\n]*\n([\s\S]+)\n```[^\S\n]*$/);
+	if (wrapMatch) {
+		const inner = wrapMatch[1].trim();
+		if (/^```(?:markdown|md)/.test(cleaned) || /^##\s/m.test(inner) || /^- (?:BREAKING|DEPRECATED|NEW): /m.test(inner)) cleaned = inner;
+	}
 	const fmMatch = cleaned.match(/^-{3,}\n/);
 	if (fmMatch) {
 		const afterOpen = fmMatch[0].length;
@@ -1885,13 +1908,23 @@ function cleanSectionOutput(content) {
 		if (closeMatch) cleaned = cleaned.slice(afterOpen + closeMatch.index + closeMatch[0].length).trim();
 		else cleaned = cleaned.slice(afterOpen).trim();
 	}
-	const firstMarker = cleaned.match(/^(##\s|⚠️|✅)/m);
+	const firstMarker = cleaned.match(/^(##\s|- (?:BREAKING|DEPRECATED|NEW): )/m);
 	if (firstMarker?.index && firstMarker.index > 0) {
 		const preamble = cleaned.slice(0, firstMarker.index);
 		if (/\b(?:function|const |let |var |export |return |import |async |class )\b/.test(preamble)) cleaned = cleaned.slice(firstMarker.index).trim();
 	}
+	const headingMatch = cleaned.match(/^(## .+)\n/);
+	if (headingMatch) {
+		const heading = headingMatch[1];
+		const afterFirst = headingMatch[0].length;
+		const secondIdx = cleaned.indexOf(heading, afterFirst);
+		if (secondIdx !== -1) {
+			if (secondIdx - afterFirst < 200) cleaned = cleaned.slice(secondIdx).trim();
+		}
+	}
+	cleaned = cleaned.replace(/\[source\]\(\.\/((docs|issues|discussions|releases|pkg|guide)\/)/g, "[source](./.skilld/$1");
 	cleaned = sanitizeMarkdown(cleaned);
-	if (!/^##\s/m.test(cleaned) && !/⚠️|✅|✨/.test(cleaned)) return "";
+	if (!/^##\s/m.test(cleaned) && !/^- (?:BREAKING|DEPRECATED|NEW): /m.test(cleaned) && !/\[source\]/.test(cleaned)) return "";
 	return cleaned;
 }
 const NUXT_CONFIG_FILES = [