skilld 0.11.2 → 0.12.0

package/dist/_chunks/config.mjs

@@ -17,9 +17,14 @@ function getCacheDir(name, version) {
 }
 const CACHE_DIR = join(homedir(), ".skilld");
 const REFERENCES_DIR = join(CACHE_DIR, "references");
+const REPOS_DIR = join(CACHE_DIR, "repos");
+function getRepoCacheDir(owner, repo) {
+	if (owner.includes("..") || repo.includes("..") || owner.includes("/") || repo.includes("/")) throw new Error(`Invalid repo path: ${owner}/${repo}`);
+	return join(REPOS_DIR, owner, repo);
+}
 function getPackageDbPath(name, version) {
 	return join(REFERENCES_DIR, getCacheKey(name, version), "search.db");
 }
-export { getCacheKey as a, getCacheDir as i, REFERENCES_DIR as n, getVersionKey as o, getPackageDbPath as r, CACHE_DIR as t };
+export { getRepoCacheDir as a, getVersionKey as c, getPackageDbPath as i, REFERENCES_DIR as n, getCacheDir as o, REPOS_DIR as r, getCacheKey as s, CACHE_DIR as t };
 
 //# sourceMappingURL=config.mjs.map

package/dist/_chunks/config.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"config.mjs","names":[],"sources":["../../src/cache/version.ts","../../src/cache/config.ts"],"sourcesContent":["/**\n * Version utilities\n */\n\nimport { resolve } from 'pathe'\nimport { REFERENCES_DIR } from './config.ts'\n\n/** Validate npm package name (scoped or unscoped) */\nconst VALID_PKG_NAME = /^(?:@[a-z0-9][-a-z0-9._]*\\/)?[a-z0-9][-a-z0-9._]*$/\n\n/** Validate version string (semver-ish, no path separators) */\nconst VALID_VERSION = /^[a-z0-9][-\\w.+]*$/i\n\n/**\n * Get exact version key for cache keying\n */\nexport function getVersionKey(version: string): string {\n  return version\n}\n\n/**\n * Get cache key for a package: name@version\n */\nexport function getCacheKey(name: string, version: string): string {\n  return `${name}@${getVersionKey(version)}`\n}\n\n/**\n * Get path to cached package references.\n * Validates name/version to prevent path traversal.\n */\nexport function getCacheDir(name: string, version: string): string {\n  if (!VALID_PKG_NAME.test(name))\n    throw new Error(`Invalid package name: ${name}`)\n  if (!VALID_VERSION.test(version))\n    throw new Error(`Invalid version: ${version}`)\n\n  const dir = resolve(REFERENCES_DIR, getCacheKey(name, version))\n  if (!dir.startsWith(REFERENCES_DIR))\n    throw new Error(`Path traversal detected: ${dir}`)\n  return dir\n}\n","/**\n * Cache configuration\n */\n\nimport { homedir } from 'node:os'\nimport { join } from 'pathe'\nimport { getCacheKey } from './version.ts'\n\n/** Global cache directory */\nexport const CACHE_DIR = join(homedir(), '.skilld')\n\n/** References subdirectory */\nexport const REFERENCES_DIR = join(CACHE_DIR, 'references')\n\n/** Get search DB path for a specific package@version */\nexport function getPackageDbPath(name: string, version: string): string {\n  return join(REFERENCES_DIR, getCacheKey(name, version), 'search.db')\n}\n"],"mappings":";;AAQA,MAAM,iBAAiB;AAGvB,MAAM,gBAAgB;AAKtB,SAAgB,cAAc,SAAyB;AACrD,QAAO;;AAMT,SAAgB,YAAY,MAAc,SAAyB;AACjE,QAAO,GAAG,KAAK,GAAG,cAAc,QAAQ;;AAO1C,SAAgB,YAAY,MAAc,SAAyB;AACjE,KAAI,CAAC,eAAe,KAAK,KAAK,CAC5B,OAAM,IAAI,MAAM,yBAAyB,OAAO;AAClD,KAAI,CAAC,cAAc,KAAK,QAAQ,CAC9B,OAAM,IAAI,MAAM,oBAAoB,UAAU;CAEhD,MAAM,MAAM,QAAQ,gBAAgB,YAAY,MAAM,QAAQ,CAAC;AAC/D,KAAI,CAAC,IAAI,WAAW,eAAe,CACjC,OAAM,IAAI,MAAM,4BAA4B,MAAM;AACpD,QAAO;;AC/BT,MAAa,YAAY,KAAK,SAAS,EAAE,UAAU;AAGnD,MAAa,iBAAiB,KAAK,WAAW,aAAa;AAG3D,SAAgB,iBAAiB,MAAc,SAAyB;AACtE,QAAO,KAAK,gBAAgB,YAAY,MAAM,QAAQ,EAAE,YAAY"}
+{"version":3,"file":"config.mjs","names":[],"sources":["../../src/cache/version.ts","../../src/cache/config.ts"],"sourcesContent":["/**\n * Version utilities\n */\n\nimport { resolve } from 'pathe'\nimport { REFERENCES_DIR } from './config.ts'\n\n/** Validate npm package name (scoped or unscoped) */\nconst VALID_PKG_NAME = /^(?:@[a-z0-9][-a-z0-9._]*\\/)?[a-z0-9][-a-z0-9._]*$/\n\n/** Validate version string (semver-ish, no path separators) */\nconst VALID_VERSION = /^[a-z0-9][-\\w.+]*$/i\n\n/**\n * Get exact version key for cache keying\n */\nexport function getVersionKey(version: string): string {\n  return version\n}\n\n/**\n * Get cache key for a package: name@version\n */\nexport function getCacheKey(name: string, version: string): string {\n  return `${name}@${getVersionKey(version)}`\n}\n\n/**\n * Get path to cached package references.\n * Validates name/version to prevent path traversal.\n */\nexport function getCacheDir(name: string, version: string): string {\n  if (!VALID_PKG_NAME.test(name))\n    throw new Error(`Invalid package name: ${name}`)\n  if (!VALID_VERSION.test(version))\n    throw new Error(`Invalid version: ${version}`)\n\n  const dir = resolve(REFERENCES_DIR, getCacheKey(name, version))\n  if (!dir.startsWith(REFERENCES_DIR))\n    throw new Error(`Path traversal detected: ${dir}`)\n  return dir\n}\n","/**\n * Cache configuration\n */\n\nimport { homedir } from 'node:os'\nimport { join } from 'pathe'\nimport { getCacheKey } from './version.ts'\n\n/** Global cache directory */\nexport const CACHE_DIR = join(homedir(), '.skilld')\n\n/** References subdirectory */\nexport const REFERENCES_DIR = join(CACHE_DIR, 'references')\n\n/** Repo-level cache (issues, discussions, releases shared across monorepo packages) */\nexport const REPOS_DIR = join(CACHE_DIR, 'repos')\n\n/** Get repo cache dir for owner/repo with path traversal validation */\nexport function getRepoCacheDir(owner: string, repo: string): string {\n  if (owner.includes('..') || repo.includes('..') || owner.includes('/') || repo.includes('/'))\n    throw new Error(`Invalid repo path: ${owner}/${repo}`)\n  return join(REPOS_DIR, owner, repo)\n}\n\n/** Get search DB path for a specific package@version */\nexport function getPackageDbPath(name: string, version: string): string {\n  return join(REFERENCES_DIR, getCacheKey(name, version), 'search.db')\n}\n"],"mappings":";;AAQA,MAAM,iBAAiB;AAGvB,MAAM,gBAAgB;AAKtB,SAAgB,cAAc,SAAyB;AACrD,QAAO;;AAMT,SAAgB,YAAY,MAAc,SAAyB;AACjE,QAAO,GAAG,KAAK,GAAG,cAAc,QAAQ;;AAO1C,SAAgB,YAAY,MAAc,SAAyB;AACjE,KAAI,CAAC,eAAe,KAAK,KAAK,CAC5B,OAAM,IAAI,MAAM,yBAAyB,OAAO;AAClD,KAAI,CAAC,cAAc,KAAK,QAAQ,CAC9B,OAAM,IAAI,MAAM,oBAAoB,UAAU;CAEhD,MAAM,MAAM,QAAQ,gBAAgB,YAAY,MAAM,QAAQ,CAAC;AAC/D,KAAI,CAAC,IAAI,WAAW,eAAe,CACjC,OAAM,IAAI,MAAM,4BAA4B,MAAM;AACpD,QAAO;;AC/BT,MAAa,YAAY,KAAK,SAAS,EAAE,UAAU;AAGnD,MAAa,iBAAiB,KAAK,WAAW,aAAa;AAG3D,MAAa,YAAY,KAAK,WAAW,QAAQ;AAGjD,SAAgB,gBAAgB,OAAe,MAAsB;AACnE,KAAI,MAAM,SAAS,KAAK,IAAI,KAAK,SAAS,KAAK,IAAI,MAAM,SAAS,IAAI,IAAI,KAAK,SAAS,IAAI,CAC1F,OAAM,IAAI,MAAM,sBAAsB,MAAM,GAAG,OAAO;AACxD,QAAO,KAAK,WAAW,OAAO,KAAK;;AAIrC,SAAgB,iBAAiB,MAAc,SAAyB;AACtE,QAAO,KAAK,gBAAgB,YAAY,MAAM,QAAQ,EAAE,YAAY"}

package/dist/_chunks/detect-imports.mjs

@@ -1,7 +1,7 @@
 import { t as __exportAll } from "./chunk.mjs";
-import { _ as writeSections, b as sanitizeMarkdown, h as readCachedSection, y as repairMarkdown } from "./storage.mjs";
+import { S as sanitizeMarkdown, g as readCachedSection, v as writeSections, x as repairMarkdown } from "./storage.mjs";
 import { t as yamlEscape } from "./yaml.mjs";
-import { i as getPackageRules, r as getFilePatterns } from "./package-registry.mjs";
+import { a as getPackageRules, i as getFilePatterns } from "./package-registry.mjs";
 import { homedir } from "node:os";
 import { dirname, join, relative } from "pathe";
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
@@ -554,14 +554,21 @@ function maxItems(min, max, sectionCount) {
 	const scale = budgetScale(sectionCount);
 	return Math.max(min, Math.round(max * scale));
 }
+function releaseBoost(significantReleases, minorVersion) {
+	const combined = (!significantReleases ? 0 : significantReleases <= 5 ? 0 : significantReleases <= 15 ? 1 : 2) + (!minorVersion ? 0 : minorVersion <= 3 ? 0 : minorVersion <= 10 ? 1 : 2);
+	if (combined <= 0) return 1;
+	if (combined <= 2) return 1.3;
+	return 1.6;
+}
 function budgetScale(sectionCount) {
 	if (!sectionCount || sectionCount <= 1) return 1;
 	if (sectionCount === 2) return .85;
 	if (sectionCount === 3) return .7;
 	return .6;
 }
-function apiChangesSection({ packageName, version, hasReleases, hasChangelog, hasDocs, hasIssues, hasDiscussions, features, enabledSectionCount }) {
+function apiChangesSection({ packageName, version, hasReleases, hasChangelog, hasDocs, hasIssues, hasDiscussions, pkgFiles, features, enabledSectionCount, releaseCount }) {
 	const [, major, minor] = version?.match(/^(\d+)\.(\d+)/) ?? [];
+	const boost = releaseBoost(releaseCount, minor ? Number(minor) : void 0);
 	const searchHints = [];
 	if (features?.search !== false) {
 		searchHints.push(`\`npx -y skilld search "deprecated" -p ${packageName}\``, `\`npx -y skilld search "breaking" -p ${packageName}\``);
@@ -643,21 +650,29 @@ This section documents version-specific API changes — prioritize recent major/
 - NEW: \`useTemplateRef()\` — new in v3.5, replaces \`$refs\` pattern [source](./.skilld/releases/v3.5.0.md)
 
 - BREAKING: \`db.query()\` — returns \`{ rows }\` not raw array since v4 [source](./.skilld/docs/migration.md)
+
+**Also changed:** \`defineModel()\` stable v3.4 · \`onWatcherCleanup()\` new v3.5 · \`Suspense\` stable v3.5
 </format-example>
 
-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.`,
+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.
+
+**Tiered format:** Top-scoring items get full detailed entries. Remaining relevant items go in a compact "**Also changed:**" line at the end — API name + brief label, separated by \` · \`. This surfaces more changes without bloating the section.`,
 		rules: [
-			`- **API Changes:** ${maxItems(6, 12, enabledSectionCount)} items from version history, MAX ${maxLines(50, 80, enabledSectionCount)} lines`,
+			`- **API Changes:** ${maxItems(6, Math.round(12 * boost), enabledSectionCount)} detailed items + compact "Also changed" line for remaining, MAX ${maxLines(50, Math.round(80 * boost), enabledSectionCount)} lines`,
 			"- **Recency:** Only include changes from the current major version and the previous→current migration. Exclude changes from older major versions entirely — users already migrated past them",
 			"- Focus on APIs that CHANGED, not general conventions or gotchas",
 			"- New APIs get NEW: prefix, deprecated/breaking get BREAKING: or DEPRECATED: prefix",
-			"- **Experimental APIs:** Append `(experimental)` to any API behind an experimental/unstable import path or flag. MAX 2 experimental items",
+			"- **Experimental APIs:** Append `(experimental)` to ALL items for unstable/experimental APIs — every mention, not just the first. MAX 2 experimental items",
+			pkgFiles?.some((f) => f.endsWith(".d.ts")) ? "- **Verify before including:** Search for API names in `.d.ts` type definitions or source exports. If you searched and cannot find the export, do NOT include the item — you may be confusing it with a similar API from a different package or version" : "- **Verify before including:** Cross-reference API names against release notes, changelogs, or docs. Do NOT include APIs you infer from similar packages — only include APIs explicitly named in the references",
+			"- **Framework-specific sourcing:** When docs have framework-specific subdirectories (e.g., `vue/`, `react/`), always cite the framework-specific version. Never cite React migration guides as sources in a Vue skill when equivalent Vue docs exist",
 			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)
 	};
 }
-function bestPracticesSection({ packageName, hasIssues, hasDiscussions, hasReleases, hasChangelog, hasDocs, features, enabledSectionCount }) {
+function bestPracticesSection({ packageName, hasIssues, hasDiscussions, hasReleases, hasChangelog, hasDocs, pkgFiles, features, enabledSectionCount, releaseCount, version }) {
+	const [, , minor] = version?.match(/^(\d+)\.(\d+)/) ?? [];
+	const boost = 1 + (releaseBoost(releaseCount, minor ? Number(minor) : void 0) - 1) * .5;
 	const searchHints = [];
 	if (features?.search !== false) searchHints.push(`\`npx -y skilld search "recommended" -p ${packageName}\``, `\`npx -y skilld search "avoid" -p ${packageName}\``);
 	const referenceWeights = [];
@@ -720,10 +735,12 @@ instance.init({ ... })
 
 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`,
-			"- **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",
+			`- **${maxItems(4, Math.round(10 * boost), enabledSectionCount)} best practice items**`,
+			`- **MAX ${maxLines(80, Math.round(150 * boost), enabledSectionCount)} lines** for best practices section`,
+			pkgFiles?.some((f) => f.endsWith(".d.ts")) ? "- **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. If you cannot find an export, do NOT include it" : "- **Verify before including:** Confirm file paths exist via Glob/Read before linking. Only document APIs explicitly named in docs, release notes, or changelogs — do NOT infer API names from similar packages",
+			"- **Source quality:** Issues and discussions are only valid sources if they contain a maintainer response, accepted answer, or confirmed workaround. Do NOT cite bare issue titles, one-line feature requests, or unresolved questions as sources",
+			"- **Framework-specific sourcing:** When docs have framework-specific subdirectories (e.g., `vue/`, `react/`), always prefer the framework-specific version over shared or other-framework docs. Never cite React examples in a Vue skill",
+			"- **Diversity:** Cover at least 3 distinct areas of the library. Count items per feature — if any single feature exceeds 40% of items, replace the excess with items from underrepresented areas",
 			"- **Experimental APIs:** Mark unstable/experimental features with `(experimental)` in the description. **MAX 1 experimental item** — prioritize stable, production-ready patterns that most users need"
 		]
 	};
@@ -824,6 +841,12 @@ function buildSectionPrompt(opts) {
 		...opts,
 		versionContext
 	});
+	const hasDocs = !!opts.docFiles?.some((f) => f.includes("/docs/"));
+	const releaseCount = opts.docFiles?.filter((f) => {
+		if (!f.includes("/releases/")) return false;
+		const m = f.match(/v\d+\.(\d+)\.(\d+)\.md$/);
+		return m && (m[1] === "0" || m[2] === "0");
+	}).length;
 	const sectionDef = getSectionDef(section, {
 		packageName,
 		version,
@@ -831,9 +854,11 @@ function buildSectionPrompt(opts) {
 		hasDiscussions,
 		hasReleases,
 		hasChangelog,
-		hasDocs: !!opts.docFiles?.some((f) => f.includes("/docs/")),
+		hasDocs,
+		pkgFiles: opts.pkgFiles,
 		features: opts.features,
-		enabledSectionCount: opts.enabledSectionCount
+		enabledSectionCount: opts.enabledSectionCount,
+		releaseCount
 	}, customPrompt);
 	if (!sectionDef) return "";
 	const outputFile = SECTION_OUTPUT_FILES[section];
@@ -844,11 +869,11 @@ function buildSectionPrompt(opts) {
 		`- **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 docs/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). Package directories are often gitignored — if you search `pkg/`, pass `no_ignore: true` to avoid silent empty results."
-	];
+		opts.pkgFiles?.some((f) => f.endsWith(".d.ts")) ? "- **To verify API exports:** Read the `.d.ts` file directly (see Types row in references). Package directories are often gitignored — if you search `pkg/`, pass `no_ignore: true` to avoid silent empty results." : ""
+	].filter(Boolean);
 	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")}` : ""}
 
 ## Task
@@ -883,12 +908,8 @@ function buildAllSectionPrompts(opts) {
 function sanitizeName(name) {
 	return name.toLowerCase().replace(/[^a-z0-9._]+/g, "-").replace(/^[.\-]+|[.\-]+$/g, "").slice(0, 255) || "unnamed-skill";
 }
-function computeSkillDirName(packageName, repoUrl) {
-	if (repoUrl) {
-		const match = repoUrl.match(/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?(?:[/#]|$)/);
-		if (match) return sanitizeName(`${match[1]}-${match[2]}`);
-	}
-	return sanitizeName(packageName);
+function computeSkillDirName(packageName) {
+	return `${sanitizeName(packageName)}-skilld`;
 }
 function installSkillForAgents(skillName, skillContent, options = {}) {
 	const isGlobal = options.global ?? false;
@@ -1056,7 +1077,7 @@ function generateFrontmatter({ name, version, description: pkgDescription, globs
 	if (desc.length > 1024) desc = `${desc.slice(0, 1021)}...`;
 	const lines = [
 		"---",
-		`name: ${dirName ?? sanitizeName(name)}`,
+		`name: ${dirName ?? computeSkillDirName(name)}`,
 		`description: ${yamlEscape(desc)}`
 	];
 	const metaEntries = [];
@@ -1810,7 +1831,7 @@ function shortenPath(p) {
 	return parts.length > 2 ? `.../${parts.slice(-2).join("/")}` : p;
 }
 const SECTION_MAX_LINES = {
-	"api-changes": 160,
+	"api-changes": 210,
 	"best-practices": 300,
 	"custom": 160
 };