Compare commits

..
7 Commits
Author SHA1 Message Date
Rohit Ghumare e569046776 chore: release v1.11.0 2026-02-03 14:38:15 +00:00
Rohit Ghumare 5bd7ebf607 feat: viral growth features — quick setup, badges, matrix, SKILL.md, federated search (#41)
* feat: add viral growth features (quick setup, badges, matrix, SKILL.md, federated search)

Tier 2: skillkit quick zero-friction entry, shareable badge generator,
agent compatibility matrix on website.

Tier 3: reposition as npm for agent skills, SKILL.md validate/init/check
commands, federated GitHub skill search with --federated flag on find.

* fix: matrix filtering, path traversal, cross-platform paths, fetch timeout

- CompatibilityMatrix: query matching agents now shows all categories
  (and vice versa) instead of hiding both dimensions independently
- quick.ts: sanitize skill names and validate targetInstallPath stays
  inside installDir before rmSync/cpSync/symlinkSync
- skillmd.ts: use path.relative() instead of string replace for
  cross-platform path display
- registry: add AbortController timeout (10s default) and distinct
  RateLimitError on 403 instead of silent empty return
- find.ts: handle RateLimitError with user-facing message
- Add quick-security.test.ts regression tests for path traversal

* fix: harden isPathInside with path.resolve, propagate RateLimitError

- isPathInside now uses path.resolve() + path.sep comparison instead of
  naive string replacement, fixing detection of paths completely outside
  the parent directory (both packages/core and src/core copies)
- FederatedSearch.search re-throws RateLimitError from rejected
  Promise.allSettled results so callers (find.ts) can handle 403s
- Updated security test to use the corrected isPathInside logic

* fix: use GITHUB_TOKEN/GH_TOKEN for authenticated GitHub API requests

GitHubSkillRegistry now reads GITHUB_TOKEN or GH_TOKEN from env and
sends Bearer auth header, raising the rate limit from 10 to 30 req/min
for code search. Matches the guidance shown to users on 403 errors.
2026-02-03 13:48:35 +00:00
Rohit Ghumare 549a21ad84 chore: release v1.10.0 2026-02-02 23:33:12 +00:00
Rohit Ghumare 109f00cd95 feat(core): add QMD-inspired hybrid search pipeline (#40)
* feat(core): add QMD-inspired hybrid search pipeline

Implement a hybrid search system combining vector embeddings with keyword search:

- Vector embeddings using node-llama-cpp with GGUF models (nomic-embed-text)
- RRF (Reciprocal Rank Fusion) for combining multiple rankers
- Query expansion with LLM and synonym fallback
- Position-aware score blending (different weights for top3, top10, rest)
- SQLite storage with sqlite-vec extension (falls back to in-memory)
- Auto-download of local GGUF models (~2GB)

New search module:
- embeddings.ts: Vector embedding generation service
- vector-store.ts: SQLite-based vector storage
- rrf.ts: RRF fusion algorithm
- expansion.ts: Query expansion with caching
- hybrid.ts: Main hybrid search pipeline
- local-models.ts: GGUF model management

CLI integration:
- skillkit recommend --hybrid: Enable hybrid search
- skillkit recommend --expand: Enable query expansion
- skillkit recommend --rerank: Enable LLM re-ranking
- skillkit recommend --build-index: Build embedding index

Tests: 56 new tests for search module (all passing)

* fix(search): address CodeRabbit review findings

- Add missing beforeEach import in embeddings.test.ts
- Update optional dependencies to current versions
- Fix weights/variations length mismatch in expansion.ts
- Avoid mutating input arrays in rrf.ts mergeRankings
- Delete orphaned chunk vectors in vector-store.ts delete() and clear()
- Add comment for empty catch block in vector-store.ts
- Make hybridSearch helper use buildIndex for true hybrid search
- Handle graceful degradation when embeddings unavailable
- Add node-llama-cpp mock in hybrid.test.ts

* fix(search): address CodeRabbit review round 2

- Fix gemma GGUF URL to point to valid community repo (bartowski)
- Add SQL injection protection for table names in vector-store.ts
- Fix resource leak with try/finally in hybridSearch helper
- Add backpressure handling for large model downloads
- Clamp startLine to non-negative in chunk calculation
- Add runtime validation warning for --expand/--rerank without --hybrid
- Update node-llama-cpp API usage (createEmbeddingContext, createContext)
- Update pnpm-lock.yaml for new optional dependency versions

* fix(search): use @ts-ignore for optional node-llama-cpp imports

CI doesn't install optional dependencies, so @ts-ignore is needed
instead of @ts-expect-error to suppress module not found errors.
2026-02-02 23:28:08 +00:00
Rohit Ghumare e3d7e0e28f feat(marketplace): add beautiful-mermaid skill
Add beautiful-mermaid to the skills marketplace:
- Render Mermaid diagrams as beautiful SVGs or ASCII art
- 5 diagram types: flowchart, sequence, class, ER, state
- 15 built-in themes + Shiki/VS Code theme integration
- Zero DOM dependencies, works in Node.js/Bun/Deno/browsers

Source: rohitg00/beautiful-mermaid
2026-02-02 17:42:09 +00:00
Rohit Ghumare 6cbbdabf59 feat(website): add dynamic stats from npm and GitHub APIs (#39)
* feat(website): add dynamic stats from npm and GitHub APIs

- Create useStats hook to fetch real-time version, downloads, and stars
- Replace hardcoded values in App.tsx stats bar with dynamic data
- Replace hardcoded version in Hero.tsx badge with dynamic data
- Add 5-minute cache to reduce API calls
- Fallback to default values if APIs fail

* fix: address CodeRabbit and Devin review comments

- Fix duplicate API calls: remove useStats from Hero, pass version as prop from App
- Fix falsy checks: use typeof checks for downloads and stargazers_count
  to correctly handle zero values instead of showing defaults
2026-02-02 17:38:48 +00:00
Rohit Ghumare c1c179217d fix(website): update version to 1.9.0 2026-02-02 17:09:24 +00:00
48 changed files with 6388 additions and 40 deletions
+5 -2
View File
@@ -14,10 +14,13 @@
[![Website](https://img.shields.io/badge/Website-agenstskills.com-black)](https://agenstskills.com)
[![Docs](https://img.shields.io/badge/Docs-agenstskills.com/docs-blue)](https://agenstskills.com/docs)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![SKILL.md](https://img.shields.io/badge/SKILL.md-compatible-black?style=flat-square)](https://agenstskills.com)
## Supercharge Every AI Coding Agent
## One Skill. Every Agent.
**Give your AI agents new abilities with portable, reusable skills.** Install from a curated marketplace, create your own, and use them across Claude Code, Cursor, Codex, Windsurf, GitHub Copilot, and 27 more agents (32 total).
**The package manager for AI agent skills. Install, translate, and share skills across 32 coding agents.**
> Think npm, but for AI agent skills. Write once, deploy to Claude Code, Cursor, Codex, Windsurf, Copilot, and 27 more.
> **What are AI Agent Skills?** Skills are instruction files that teach AI coding agents how to handle specific tasks - like processing PDFs, following React best practices, or enforcing security patterns. Think of them as plugins for your AI assistant.
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "skillkit",
"version": "1.9.0",
"version": "1.11.0",
"description": "Supercharge AI coding agents with portable skills. Install, translate, and share skills across Claude Code, Cursor, Codex, Copilot & 13 more",
"type": "module",
"bin": {
+9
View File
@@ -98,6 +98,10 @@ import {
GuidelineCreateCommand,
GuidelineRemoveCommand,
TreeCommand,
QuickCommand,
SkillMdValidateCommand,
SkillMdInitCommand,
SkillMdCheckCommand,
} from '@skillkit/cli';
const __filename = fileURLToPath(import.meta.url);
@@ -220,4 +224,9 @@ cli.register(GuidelineRemoveCommand);
cli.register(TreeCommand);
cli.register(QuickCommand);
cli.register(SkillMdValidateCommand);
cli.register(SkillMdInitCommand);
cli.register(SkillMdCheckCommand);
cli.runExit(process.argv.slice(2));
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "skillkit-docs",
"version": "1.9.0",
"version": "1.10.0",
"private": true,
"scripts": {
"build": "next build",
+33 -4
View File
@@ -12,6 +12,9 @@ import { Attribution } from './components/Attribution';
import { AdvancedFeatures } from './components/AdvancedFeatures';
import { UseCases } from './components/UseCases';
import { TeamEnterprise } from './components/TeamEnterprise';
import { BadgeGenerator } from './components/BadgeGenerator';
import { CompatibilityMatrix } from './components/CompatibilityMatrix';
import { useStats } from './hooks/useStats';
const GITHUB_ICON = (
<svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
@@ -34,6 +37,8 @@ function scrollToSection(e: React.MouseEvent, sectionId: string): void {
}
export default function App(): React.ReactElement {
const stats = useStats();
return (
<div className="min-h-screen text-zinc-100 font-sans selection:bg-white selection:text-black" style={{ backgroundColor: '#000000' }}>
<nav className="fixed top-0 left-0 right-0 z-50 border-b border-zinc-800 backdrop-blur-md" style={{ backgroundColor: 'rgba(0,0,0,0.9)' }}>
@@ -58,6 +63,20 @@ export default function App(): React.ReactElement {
>
Stack
</a>
<a
href="#matrix"
onClick={(e) => scrollToSection(e, 'matrix')}
className="text-zinc-500 hover:text-white transition-colors"
>
Matrix
</a>
<a
href="#badge"
onClick={(e) => scrollToSection(e, 'badge')}
className="text-zinc-500 hover:text-white transition-colors"
>
Badge
</a>
<a
href="#advanced"
onClick={(e) => scrollToSection(e, 'advanced')}
@@ -102,7 +121,7 @@ export default function App(): React.ReactElement {
</nav>
<main className="pt-14">
<Hero />
<Hero version={stats.version} />
<div className="border-b border-zinc-800/50 py-2.5" style={{ background: 'linear-gradient(to bottom, rgba(9,9,11,0.95), rgba(0,0,0,1))' }}>
<div className="mx-auto max-w-5xl px-4 sm:px-6 lg:px-8">
@@ -114,7 +133,7 @@ export default function App(): React.ReactElement {
className="flex items-center gap-1.5 text-zinc-500 hover:text-white transition-colors group"
>
<span className="text-zinc-600 group-hover:text-zinc-400">v</span>
<span className="text-white font-medium">1.8.0</span>
<span className="text-white font-medium">{stats.version}</span>
</a>
<span className="text-zinc-800">·</span>
<a
@@ -126,7 +145,7 @@ export default function App(): React.ReactElement {
<svg className="w-3 h-3 text-zinc-600 group-hover:text-zinc-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 16v1a3 3 0 003 3h10a3 3 0 003-3v-1m-4-4l-4 4m0 0l-4-4m4 4V4" />
</svg>
<span className="text-white font-medium">2.4k</span>
<span className="text-white font-medium">{stats.downloads}</span>
</a>
<span className="text-zinc-800">·</span>
<a
@@ -138,7 +157,7 @@ export default function App(): React.ReactElement {
<svg className="w-3 h-3 text-zinc-600 group-hover:text-yellow-500" fill="currentColor" viewBox="0 0 24 24">
<path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z" />
</svg>
<span className="text-white font-medium">66</span>
<span className="text-white font-medium">{stats.stars}</span>
</a>
<span className="text-zinc-800 hidden sm:inline">·</span>
<a
@@ -169,6 +188,16 @@ export default function App(): React.ReactElement {
<StackBuilder />
</section>
{/* Compatibility Matrix */}
<section id="matrix" style={{ scrollMarginTop: '4rem' }}>
<CompatibilityMatrix />
</section>
{/* Badge Generator */}
<section id="badge" style={{ scrollMarginTop: '4rem' }}>
<BadgeGenerator />
</section>
{/* Advanced Capabilities: Memory, Primer, Mesh, Messaging */}
<section id="advanced" style={{ scrollMarginTop: '4rem' }}>
<AdvancedFeatures />
+201
View File
@@ -0,0 +1,201 @@
import React, { useState, useMemo } from 'react';
const SKILLKIT_LOGO_SVG_BASE64 =
'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0id2hpdGUiPjxyZWN0IHdpZHRoPSI2IiBoZWlnaHQ9IjYiIHg9IjEiIHk9IjEiLz48cmVjdCB3aWR0aD0iNiIgaGVpZ2h0PSI2IiB4PSI5IiB5PSIxIi8+PHJlY3Qgd2lkdGg9IjYiIGhlaWdodD0iNiIgeD0iMSIgeT0iOSIvPjxyZWN0IHdpZHRoPSI2IiBoZWlnaHQ9IjYiIHg9IjkiIHk9IjkiLz48L3N2Zz4=';
const SUGGESTED_SKILLS = [
'react', 'typescript', 'nextjs', 'python', 'docker',
'kubernetes', 'tailwind', 'graphql', 'prisma', 'langchain',
'openai', 'rust', 'go', 'vue', 'svelte',
'security', 'testing', 'cicd', 'aws', 'terraform',
];
function encodeBadgeSegment(text: string): string {
return encodeURIComponent(text).replace(/-/g, '--');
}
function buildBadgeUrl(skills: string[]): string {
if (skills.length === 0) {
return `https://img.shields.io/badge/SkillKit-No%20Skills-555555?style=flat-square&logo=data:image/svg+xml;base64,${SKILLKIT_LOGO_SVG_BASE64}`;
}
const maxDisplay = 5;
const displayNames = skills.slice(0, maxDisplay);
const suffix = skills.length > maxDisplay ? ` +${skills.length - maxDisplay} more` : '';
const label = `SkillKit ${skills.length} skills`;
const message = displayNames.join(' | ') + suffix;
return `https://img.shields.io/badge/${encodeBadgeSegment(label)}-${encodeBadgeSegment(message)}-black?style=flat-square&logo=data:image/svg+xml;base64,${SKILLKIT_LOGO_SVG_BASE64}`;
}
export function BadgeGenerator(): React.ReactElement {
const [skills, setSkills] = useState<string[]>(['react', 'typescript', 'nextjs']);
const [inputValue, setInputValue] = useState('');
const [copiedType, setCopiedType] = useState<string | null>(null);
const badgeUrl = useMemo(() => buildBadgeUrl(skills), [skills]);
const markdown = `[![SkillKit Stack](${badgeUrl})](https://agenstskills.com)`;
const html = `<a href="https://agenstskills.com"><img src="${badgeUrl}" alt="SkillKit Stack" /></a>`;
function addSkill(skill: string): void {
const trimmed = skill.trim().toLowerCase();
if (trimmed && !skills.includes(trimmed)) {
setSkills([...skills, trimmed]);
}
setInputValue('');
}
function removeSkill(skill: string): void {
setSkills(skills.filter(s => s !== skill));
}
function handleKeyDown(e: React.KeyboardEvent<HTMLInputElement>): void {
if (e.key === 'Enter' && inputValue.trim()) {
e.preventDefault();
addSkill(inputValue);
}
}
async function copyToClipboard(text: string, type: string): Promise<void> {
try {
await navigator.clipboard.writeText(text);
setCopiedType(type);
setTimeout(() => setCopiedType(null), 2000);
} catch {
// silently ignore
}
}
const availableSuggestions = SUGGESTED_SKILLS.filter(s => !skills.includes(s));
return (
<section className="py-12 border-b border-zinc-800">
<div className="mx-auto max-w-5xl px-4 sm:px-6 lg:px-8">
<div className="mb-6">
<h2 className="text-xl font-bold text-white mb-1 font-mono">Badge Generator</h2>
<p className="text-zinc-500 font-mono text-xs">
Create a shareable badge for your skill stack. Add it to your README.
</p>
</div>
<div className="flex flex-col lg:flex-row gap-6">
<div className="flex-1 space-y-4">
<div className="relative">
<input
type="text"
value={inputValue}
onChange={(e) => setInputValue(e.target.value)}
onKeyDown={handleKeyDown}
placeholder="Type a skill name and press Enter..."
className="w-full bg-zinc-900 border border-zinc-700 text-white px-4 py-3 focus:ring-2 focus:ring-white focus:border-transparent outline-none font-mono text-sm placeholder-zinc-600"
/>
</div>
<div className="space-y-2">
<span className="text-zinc-500 text-xs font-mono block">Quick add:</span>
<div className="flex flex-wrap gap-1.5">
{availableSuggestions.slice(0, 12).map(skill => (
<button
key={skill}
onClick={() => addSkill(skill)}
className="text-[10px] sm:text-xs bg-zinc-900 text-zinc-400 px-2 sm:px-3 py-1 sm:py-1.5 border border-zinc-700 hover:border-zinc-500 hover:text-white transition-colors font-mono"
>
+ {skill}
</button>
))}
</div>
</div>
{skills.length > 0 && (
<div className="space-y-2">
<div className="flex items-center justify-between">
<div className="text-xs font-mono text-zinc-500 uppercase tracking-wider">
Skills in Badge ({skills.length})
</div>
<button
onClick={() => setSkills([])}
className="text-zinc-500 hover:text-red-400 font-mono text-xs transition-colors"
>
Clear All
</button>
</div>
<div className="flex flex-wrap gap-2">
{skills.map(skill => (
<div
key={skill}
className="flex items-center gap-1.5 bg-zinc-900/50 border border-zinc-800 px-3 py-1.5 group"
>
<span className="font-mono text-sm text-white">{skill}</span>
<button
onClick={() => removeSkill(skill)}
aria-label={`Remove ${skill}`}
className="text-zinc-600 hover:text-red-400 transition-colors opacity-0 group-hover:opacity-100 focus-visible:opacity-100"
>
<svg className="w-3 h-3" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
</svg>
</button>
</div>
))}
</div>
</div>
)}
</div>
<div className="lg:w-80 lg:flex-shrink-0">
<div className="lg:sticky lg:top-20 bg-zinc-900/30 border border-zinc-800 p-4 space-y-4">
<div className="text-xs font-mono text-zinc-500 uppercase tracking-wider">Preview</div>
<div className="flex justify-center py-3 bg-black/50 border border-zinc-800">
{skills.length > 0 ? (
<img
src={badgeUrl}
alt="SkillKit Stack Badge"
className="h-5"
/>
) : (
<span className="text-zinc-600 text-xs font-mono">Add skills to preview</span>
)}
</div>
<div className="space-y-2">
<div className="text-xs font-mono text-zinc-500">Markdown</div>
<pre className="bg-black/50 p-2 overflow-x-auto text-[10px] border border-zinc-800">
<code className="font-mono text-zinc-300 whitespace-pre-wrap break-all">
{markdown}
</code>
</pre>
<button
onClick={() => copyToClipboard(markdown, 'markdown')}
className="w-full bg-zinc-800 text-zinc-300 py-1.5 font-mono text-xs hover:bg-zinc-700 hover:text-white transition-colors flex items-center justify-center gap-1.5 border border-zinc-700"
>
{copiedType === 'markdown' ? 'Copied!' : 'Copy Markdown'}
</button>
</div>
<div className="space-y-2">
<div className="text-xs font-mono text-zinc-500">HTML</div>
<pre className="bg-black/50 p-2 overflow-x-auto text-[10px] border border-zinc-800">
<code className="font-mono text-zinc-300 whitespace-pre-wrap break-all">
{html}
</code>
</pre>
<button
onClick={() => copyToClipboard(html, 'html')}
className="w-full bg-zinc-800 text-zinc-300 py-1.5 font-mono text-xs hover:bg-zinc-700 hover:text-white transition-colors flex items-center justify-center gap-1.5 border border-zinc-700"
>
{copiedType === 'html' ? 'Copied!' : 'Copy HTML'}
</button>
</div>
<div className="text-[10px] font-mono text-zinc-600 text-center pt-2 border-t border-zinc-800">
Powered by shields.io
</div>
</div>
</div>
</div>
</div>
</section>
);
}
@@ -0,0 +1,351 @@
import React, { useState, useMemo } from 'react';
type Support = 'full' | 'partial' | 'none';
interface AgentDef {
id: string;
name: string;
icon: string;
group: string;
}
interface CategoryDef {
id: string;
name: string;
icon: string;
}
const AGENTS: AgentDef[] = [
{ id: 'claude-code', name: 'Claude Code', icon: '\u27C1', group: 'Tier 1' },
{ id: 'cursor', name: 'Cursor', icon: '\u25EB', group: 'Tier 1' },
{ id: 'codex', name: 'Codex', icon: '\u25CE', group: 'Tier 1' },
{ id: 'gemini-cli', name: 'Gemini CLI', icon: '\u2726', group: 'Tier 1' },
{ id: 'opencode', name: 'OpenCode', icon: '\u2B21', group: 'Tier 1' },
{ id: 'windsurf', name: 'Windsurf', icon: '\u25C7', group: 'Tier 1' },
{ id: 'github-copilot', name: 'Copilot', icon: '\u2318', group: 'Tier 1' },
{ id: 'goose', name: 'Goose', icon: '\u25CA', group: 'Tier 2' },
{ id: 'kilo', name: 'Kilo', icon: '\u25B3', group: 'Tier 2' },
{ id: 'kiro-cli', name: 'Kiro CLI', icon: '\u25BD', group: 'Tier 2' },
{ id: 'roo', name: 'Roo', icon: '\u25C6', group: 'Tier 2' },
{ id: 'trae', name: 'Trae', icon: '\u25A0', group: 'Tier 2' },
{ id: 'amp', name: 'AMP', icon: '\u26A1', group: 'Tier 2' },
{ id: 'cline', name: 'Cline', icon: '\u25CF', group: 'Tier 3' },
{ id: 'continue', name: 'Continue', icon: '\u25B6', group: 'Tier 3' },
{ id: 'antigravity', name: 'Antigravity', icon: '\u2191', group: 'Tier 3' },
];
const CATEGORIES: CategoryDef[] = [
{ id: 'security', name: 'Security', icon: '\u25D0' },
{ id: 'testing', name: 'Testing', icon: '\u25D2' },
{ id: 'react-frontend', name: 'React/Frontend', icon: '\u269B' },
{ id: 'backend', name: 'Backend', icon: '\u2393' },
{ id: 'devops', name: 'DevOps', icon: '\u25D1' },
{ id: 'python', name: 'Python', icon: '\u25C9' },
{ id: 'go', name: 'Go', icon: '\u25C8' },
{ id: 'typescript', name: 'TypeScript', icon: '\u25C8' },
{ id: 'database', name: 'Database', icon: '\u25A3' },
{ id: 'performance', name: 'Performance', icon: '\u25CE' },
{ id: 'documentation', name: 'Documentation', icon: '\u25A1' },
{ id: 'ai-ml', name: 'AI/ML', icon: '\u25CE' },
];
const MATRIX: Record<string, Record<string, Support>> = {
'security': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'full', 'goose': 'partial',
'kilo': 'partial', 'kiro-cli': 'partial', 'roo': 'full', 'trae': 'partial',
'amp': 'full', 'cline': 'full', 'continue': 'partial', 'antigravity': 'partial',
},
'testing': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'full', 'goose': 'full',
'kilo': 'partial', 'kiro-cli': 'partial', 'roo': 'full', 'trae': 'partial',
'amp': 'full', 'cline': 'full', 'continue': 'full', 'antigravity': 'partial',
},
'react-frontend': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'partial', 'windsurf': 'full', 'github-copilot': 'full', 'goose': 'partial',
'kilo': 'partial', 'kiro-cli': 'partial', 'roo': 'full', 'trae': 'full',
'amp': 'full', 'cline': 'full', 'continue': 'full', 'antigravity': 'none',
},
'backend': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'full', 'goose': 'full',
'kilo': 'partial', 'kiro-cli': 'partial', 'roo': 'full', 'trae': 'partial',
'amp': 'full', 'cline': 'full', 'continue': 'full', 'antigravity': 'partial',
},
'devops': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'partial', 'github-copilot': 'full', 'goose': 'partial',
'kilo': 'partial', 'kiro-cli': 'none', 'roo': 'partial', 'trae': 'partial',
'amp': 'full', 'cline': 'partial', 'continue': 'partial', 'antigravity': 'none',
},
'python': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'full', 'goose': 'full',
'kilo': 'partial', 'kiro-cli': 'partial', 'roo': 'full', 'trae': 'partial',
'amp': 'full', 'cline': 'full', 'continue': 'full', 'antigravity': 'partial',
},
'go': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'partial', 'github-copilot': 'full', 'goose': 'partial',
'kilo': 'none', 'kiro-cli': 'none', 'roo': 'partial', 'trae': 'partial',
'amp': 'partial', 'cline': 'partial', 'continue': 'partial', 'antigravity': 'none',
},
'typescript': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'full', 'goose': 'full',
'kilo': 'partial', 'kiro-cli': 'partial', 'roo': 'full', 'trae': 'full',
'amp': 'full', 'cline': 'full', 'continue': 'full', 'antigravity': 'partial',
},
'database': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'partial', 'windsurf': 'partial', 'github-copilot': 'full', 'goose': 'partial',
'kilo': 'none', 'kiro-cli': 'none', 'roo': 'partial', 'trae': 'partial',
'amp': 'partial', 'cline': 'partial', 'continue': 'partial', 'antigravity': 'none',
},
'performance': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'partial', 'windsurf': 'partial', 'github-copilot': 'partial', 'goose': 'partial',
'kilo': 'none', 'kiro-cli': 'none', 'roo': 'partial', 'trae': 'partial',
'amp': 'partial', 'cline': 'partial', 'continue': 'partial', 'antigravity': 'none',
},
'documentation': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'full', 'windsurf': 'full', 'github-copilot': 'full', 'goose': 'full',
'kilo': 'partial', 'kiro-cli': 'partial', 'roo': 'full', 'trae': 'full',
'amp': 'full', 'cline': 'full', 'continue': 'full', 'antigravity': 'partial',
},
'ai-ml': {
'claude-code': 'full', 'cursor': 'full', 'codex': 'full', 'gemini-cli': 'full',
'opencode': 'partial', 'windsurf': 'partial', 'github-copilot': 'partial', 'goose': 'partial',
'kilo': 'none', 'kiro-cli': 'none', 'roo': 'partial', 'trae': 'partial',
'amp': 'partial', 'cline': 'partial', 'continue': 'partial', 'antigravity': 'none',
},
};
const SUPPORT_CONFIG: Record<Support, { color: string; bg: string; label: string }> = {
full: { color: 'text-green-400', bg: 'bg-green-400/10', label: 'Full' },
partial: { color: 'text-yellow-400', bg: 'bg-yellow-400/10', label: 'Partial' },
none: { color: 'text-red-400', bg: 'bg-red-400/10', label: 'None' },
};
const SUPPORT_SCORE: Record<Support, number> = { full: 2, partial: 1, none: 0 };
function SupportCell({ support }: { support: Support }): React.ReactElement {
const config = SUPPORT_CONFIG[support];
return (
<td className="px-1 py-2 text-center">
<div className={`inline-flex items-center justify-center w-5 h-5 rounded-full ${config.bg}`}>
<span className={`text-[10px] font-bold ${config.color}`}>
{support === 'full' ? '\u2713' : support === 'partial' ? '\u25CB' : '\u2715'}
</span>
</div>
</td>
);
}
function getAgentScore(agentId: string): number {
return Object.values(MATRIX).reduce((sum, row) => sum + SUPPORT_SCORE[row[agentId] || 'none'], 0);
}
function getMaxScore(): number {
return CATEGORIES.length * 2;
}
export function CompatibilityMatrix(): React.ReactElement {
const [filter, setFilter] = useState('');
const [groupFilter, setGroupFilter] = useState<string | null>(null);
const groups = useMemo(() => {
const seen = new Set<string>();
return AGENTS.reduce<string[]>((acc, a) => {
if (!seen.has(a.group)) {
seen.add(a.group);
acc.push(a.group);
}
return acc;
}, []);
}, []);
const { filteredAgents, filteredCategories } = useMemo(() => {
let agents = AGENTS;
if (groupFilter) {
agents = agents.filter(a => a.group === groupFilter);
}
if (!filter.trim()) {
return { filteredAgents: agents, filteredCategories: CATEGORIES };
}
const q = filter.toLowerCase();
const matchedAgents = agents.filter(a =>
a.name.toLowerCase().includes(q) || a.id.toLowerCase().includes(q)
);
const matchedCategories = CATEGORIES.filter(c =>
c.name.toLowerCase().includes(q) || c.id.toLowerCase().includes(q)
);
return {
filteredAgents: matchedAgents.length > 0 ? matchedAgents : (matchedCategories.length > 0 ? agents : []),
filteredCategories: matchedCategories.length > 0 ? matchedCategories : (matchedAgents.length > 0 ? CATEGORIES : []),
};
}, [filter, groupFilter]);
const maxScore = getMaxScore();
return (
<section className="py-12 border-b border-zinc-800" style={{ backgroundColor: '#09090b' }}>
<div className="mx-auto max-w-5xl px-4 sm:px-6 lg:px-8">
<div className="flex flex-col sm:flex-row sm:items-center justify-between gap-2 mb-6">
<div>
<h2 className="text-lg sm:text-xl font-bold text-white mb-1 font-mono">Compatibility Matrix</h2>
<p className="text-zinc-500 font-mono text-[10px] sm:text-xs">
Skill support across 16 agents and 12 categories.
</p>
</div>
<div className="flex items-center gap-2">
<span className="w-2 h-2 bg-green-500 rounded-full"></span>
<span className="text-[10px] sm:text-xs font-mono text-zinc-500">Updated Feb 2026</span>
</div>
</div>
<div className="flex flex-col sm:flex-row gap-2 sm:gap-3 mb-6">
<div className="relative flex-1">
<svg className="absolute left-2.5 top-1/2 -translate-y-1/2 w-3.5 h-3.5 text-zinc-600" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
</svg>
<input
type="text"
value={filter}
onChange={(e) => setFilter(e.target.value)}
placeholder="Filter agents or categories..."
className="w-full bg-black border border-zinc-800 text-zinc-300 placeholder-zinc-700 font-mono text-xs px-8 py-2 focus:outline-none focus:border-zinc-600 transition-colors"
/>
{filter && (
<button
onClick={() => setFilter('')}
className="absolute right-2.5 top-1/2 -translate-y-1/2 text-zinc-600 hover:text-zinc-400 transition-colors"
>
<svg className="w-3.5 h-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
</svg>
</button>
)}
</div>
<div className="flex gap-1.5">
<button
onClick={() => setGroupFilter(null)}
className={`px-2.5 py-1.5 font-mono text-[10px] sm:text-xs transition-all ${
groupFilter === null
? 'bg-white text-black'
: 'bg-zinc-900 text-zinc-400 border border-zinc-800 hover:border-zinc-600 hover:text-white'
}`}
>
All
</button>
{groups.map(g => (
<button
key={g}
onClick={() => setGroupFilter(groupFilter === g ? null : g)}
className={`px-2.5 py-1.5 font-mono text-[10px] sm:text-xs transition-all ${
groupFilter === g
? 'bg-white text-black'
: 'bg-zinc-900 text-zinc-400 border border-zinc-800 hover:border-zinc-600 hover:text-white'
}`}
>
{g}
</button>
))}
</div>
</div>
<div className="flex items-center gap-4 mb-4">
{Object.entries(SUPPORT_CONFIG).map(([key, config]) => (
<div key={key} className="flex items-center gap-1.5">
<div className={`w-3 h-3 rounded-full ${config.bg} flex items-center justify-center`}>
<span className={`text-[8px] font-bold ${config.color}`}>
{key === 'full' ? '\u2713' : key === 'partial' ? '\u25CB' : '\u2715'}
</span>
</div>
<span className="text-[10px] font-mono text-zinc-500">{config.label}</span>
</div>
))}
</div>
<div className="overflow-x-auto -mx-4 px-4 sm:mx-0 sm:px-0">
<div className="min-w-[700px]">
<table className="w-full border-collapse font-mono text-[10px]">
<thead>
<tr className="border-b border-zinc-800">
<th className="text-left text-zinc-500 uppercase tracking-wider py-2 pr-3 sticky left-0 bg-[#09090b] z-10 min-w-[120px]">
Category
</th>
{filteredAgents.map(agent => (
<th key={agent.id} className="px-1 py-2 text-center">
<div className="flex flex-col items-center gap-0.5">
<span className="text-sm">{agent.icon}</span>
<span className="text-zinc-400 whitespace-nowrap max-w-[50px] truncate" title={agent.name}>
{agent.name.length > 7 ? agent.name.slice(0, 7) : agent.name}
</span>
</div>
</th>
))}
</tr>
</thead>
<tbody>
{filteredCategories.map(category => (
<tr key={category.id} className="border-b border-zinc-800/50 hover:bg-zinc-900/50 transition-colors">
<td className="py-2 pr-3 sticky left-0 bg-[#09090b] z-10">
<div className="flex items-center gap-1.5">
<span className="text-zinc-600">{category.icon}</span>
<span className="text-zinc-300 whitespace-nowrap">{category.name}</span>
</div>
</td>
{filteredAgents.map(agent => (
<SupportCell
key={agent.id}
support={MATRIX[category.id]?.[agent.id] || 'none'}
/>
))}
</tr>
))}
</tbody>
<tfoot>
<tr className="border-t border-zinc-700">
<td className="py-3 pr-3 sticky left-0 bg-[#09090b] z-10">
<span className="text-zinc-400 font-bold uppercase tracking-wider">Score</span>
</td>
{filteredAgents.map(agent => {
const score = getAgentScore(agent.id);
const pct = Math.round((score / maxScore) * 100);
const color = pct >= 80 ? 'text-green-400' : pct >= 50 ? 'text-yellow-400' : 'text-red-400';
return (
<td key={agent.id} className="px-1 py-3 text-center">
<div className={`font-bold text-xs ${color}`}>{pct}%</div>
<div className="text-zinc-600 text-[9px]">{score}/{maxScore}</div>
</td>
);
})}
</tr>
</tfoot>
</table>
</div>
</div>
{filteredAgents.length === 0 && (
<div className="text-center py-8 text-zinc-600 font-mono text-sm">
No agents match your filter.
</div>
)}
{filteredCategories.length === 0 && filteredAgents.length > 0 && (
<div className="text-center py-8 text-zinc-600 font-mono text-sm">
No categories match your filter.
</div>
)}
</div>
</section>
);
}
+2 -2
View File
@@ -9,7 +9,7 @@ interface Feature {
const FEATURES: Feature[] = [
{
title: 'Smart Recommendations',
description: 'AI analyzes your codebase and suggests perfect skills.',
description: 'AI analyzes your codebase and recommends from 15,000+ skills.',
icon: (
<svg className="w-5 h-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" />
@@ -18,7 +18,7 @@ const FEATURES: Feature[] = [
},
{
title: 'Auto Translation',
description: 'Write once, deploy to 32 agents. Zero manual conversion.',
description: 'The npm for agent skills. Write once, auto-translate to 32 formats.',
icon: (
<svg className="w-5 h-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M8 7h12m0 0l-4-4m4 4l-4 4m0 6H4m0 0l4 4m-4-4l4-4" />
+11 -7
View File
@@ -1,6 +1,10 @@
import React, { useState, useEffect } from 'react';
import { Button } from './Button';
interface HeroProps {
version: string;
}
const ASCII_LOGO = `
███████╗██╗ ██╗██╗██╗ ██╗ ██╗ ██╗██╗████████╗
██╔════╝██║ ██╔╝██║██║ ██║ ██║ ██╔╝██║╚══██╔══╝
@@ -55,7 +59,7 @@ const COPY_ICON = (
</svg>
);
export function Hero(): React.ReactElement {
export function Hero({ version }: HeroProps): React.ReactElement {
const [copied, setCopied] = useState(false);
const [visibleLines, setVisibleLines] = useState(0);
const [typingIndex, setTypingIndex] = useState(0);
@@ -126,18 +130,18 @@ export function Hero(): React.ReactElement {
<div className="animate-fade-in">
<div className="inline-flex items-center space-x-2 border border-zinc-800 bg-zinc-900/50 px-2 py-0.5 mb-3 backdrop-blur-sm">
<span className="flex h-1.5 w-1.5 bg-white rounded-full"></span>
<span className="text-xs font-mono text-zinc-400">v1.8.0</span>
<span className="text-xs font-mono text-zinc-400">v{version}</span>
</div>
<h1 className="text-2xl sm:text-3xl lg:text-4xl font-bold tracking-tight text-white mb-3 font-mono">
Write Once.<br />
<span className="text-zinc-500">Deploy to 32 Agents.</span>
One Skill.<br />
<span className="text-zinc-500">32 Agents. Zero Rewrites.</span>
</h1>
<p className="text-sm text-zinc-400 mb-5 max-w-lg font-mono leading-relaxed">
The universal skill platform for AI coding agents. Auto-generate instructions
with Primer, persist learnings with Memory, distribute across Mesh networks.
One CLI for Claude, Cursor, Windsurf, Copilot, and 28 more.
The package manager for AI agent skills. Install from 15,000+ skills,
auto-translate between formats, persist learnings with Memory.
Works with Claude, Cursor, Windsurf, Copilot, and 28 more.
</p>
<div className="flex flex-wrap items-center gap-3 mb-4">
+119
View File
@@ -0,0 +1,119 @@
import { useState, useEffect } from 'react';
interface Stats {
version: string;
downloads: string;
stars: number;
loading: boolean;
}
const CACHE_KEY = 'skillkit_stats_cache';
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
interface CachedStats {
data: Omit<Stats, 'loading'>;
timestamp: number;
}
function formatDownloads(count: number): string {
if (count >= 1000000) {
return `${(count / 1000000).toFixed(1)}M`;
}
if (count >= 1000) {
return `${(count / 1000).toFixed(1)}k`;
}
return count.toString();
}
function getCachedStats(): CachedStats | null {
try {
const cached = localStorage.getItem(CACHE_KEY);
if (cached) {
const parsed: CachedStats = JSON.parse(cached);
if (Date.now() - parsed.timestamp < CACHE_TTL) {
return parsed;
}
}
} catch {
// Ignore localStorage errors
}
return null;
}
function setCachedStats(data: Omit<Stats, 'loading'>): void {
try {
const cached: CachedStats = {
data,
timestamp: Date.now(),
};
localStorage.setItem(CACHE_KEY, JSON.stringify(cached));
} catch {
// Ignore localStorage errors
}
}
export function useStats(): Stats {
const [stats, setStats] = useState<Stats>({
version: '1.9.0',
downloads: '2.4k',
stars: 66,
loading: true,
});
useEffect(() => {
const cached = getCachedStats();
if (cached) {
setStats({ ...cached.data, loading: false });
return;
}
async function fetchStats(): Promise<void> {
try {
const [npmResponse, githubResponse] = await Promise.allSettled([
fetch('https://api.npmjs.org/downloads/point/last-month/skillkit'),
fetch('https://api.github.com/repos/rohitg00/skillkit'),
]);
let downloads = '2.4k';
let stars = 66;
let version = '1.9.0';
if (npmResponse.status === 'fulfilled' && npmResponse.value.ok) {
const npmData = await npmResponse.value.json();
if (typeof npmData.downloads === 'number' && Number.isFinite(npmData.downloads)) {
downloads = formatDownloads(npmData.downloads);
}
}
if (githubResponse.status === 'fulfilled' && githubResponse.value.ok) {
const githubData = await githubResponse.value.json();
if (typeof githubData.stargazers_count === 'number' && Number.isFinite(githubData.stargazers_count)) {
stars = githubData.stargazers_count;
}
}
try {
const registryResponse = await fetch('https://registry.npmjs.org/skillkit/latest');
if (registryResponse.ok) {
const registryData = await registryResponse.json();
if (registryData.version) {
version = registryData.version;
}
}
} catch {
// Use default version
}
const newStats = { version, downloads, stars };
setCachedStats(newStats);
setStats({ ...newStats, loading: false });
} catch {
setStats((prev) => ({ ...prev, loading: false }));
}
}
fetchStats();
}, []);
return stats;
}
+1 -1
View File
@@ -1,7 +1,7 @@
{
"name": "skillkit",
"private": true,
"version": "1.9.0",
"version": "1.10.0",
"type": "module",
"scripts": {
"dev": "vite",
+19 -2
View File
@@ -1,8 +1,8 @@
{
"$schema": "./schema.json",
"version": 1,
"updatedAt": "2026-01-26",
"totalSkills": 15064,
"updatedAt": "2026-02-02",
"totalSkills": 15065,
"curatedCollections": 31,
"skills": [
{
@@ -33112,6 +33112,23 @@
"k8s"
]
},
{
"id": "rohitg00/beautiful-mermaid/beautiful-mermaid",
"name": "Beautiful Mermaid",
"description": "Render Mermaid diagrams as beautiful SVGs or ASCII art. 5 diagram types, 15 themes, Shiki integration, zero DOM dependencies.",
"source": "rohitg00/beautiful-mermaid",
"tags": [
"mermaid",
"diagrams",
"visualization",
"flowchart",
"sequence",
"uml",
"ascii",
"svg",
"themes"
]
},
{
"id": "itsmostafa/aws-agent-skills/cognito",
"name": "Cognito",
+9 -3
View File
@@ -1,8 +1,8 @@
{
"name": "skillkit-monorepo",
"version": "1.9.0",
"version": "1.11.0",
"private": true,
"description": "Universal skills loader for AI coding agents - Monorepo",
"description": "The package manager for AI agent skills — install, translate, share across 32 coding agents",
"type": "module",
"scripts": {
"build": "turbo run build",
@@ -31,7 +31,13 @@
"coding-assistant",
"skill-loader",
"cli",
"monorepo"
"monorepo",
"skill-md",
"package-manager",
"plugin",
"workflow",
"automation",
"SKILL.md"
],
"author": "Rohit Ghumare",
"license": "Apache-2.0",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/agents",
"version": "1.9.0",
"version": "1.11.0",
"description": "Agent adapters for SkillKit - supports 32 AI coding agents",
"type": "module",
"main": "./dist/index.js",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/cli",
"version": "1.9.0",
"version": "1.11.0",
"description": "CLI commands for SkillKit",
"type": "module",
"main": "./dist/index.js",
@@ -0,0 +1,69 @@
import { describe, it, expect } from 'vitest';
import { join, normalize, resolve, sep } from 'node:path';
function isPathInside(child: string, parent: string): boolean {
const resolved = resolve(child);
const resolvedParent = resolve(parent);
return resolved === resolvedParent || resolved.startsWith(resolvedParent + sep);
}
function sanitizeName(name: string): string {
return name.split(/[/\\]/).pop() || name;
}
describe('Quick Command Security', () => {
describe('path traversal protection', () => {
const installDir = '/home/user/.claude/skills';
it('should block skill names that escape the install directory', () => {
const maliciousNames = ['../evil', '../../etc/passwd', '../../../tmp/bad', '..\\evil'];
for (const name of maliciousNames) {
const sanitized = sanitizeName(name);
const targetPath = normalize(join(installDir, sanitized));
expect(isPathInside(targetPath, installDir)).toBe(true);
expect(sanitized).not.toContain('..');
expect(sanitized).not.toContain('/');
expect(sanitized).not.toContain('\\');
}
});
it('should sanitize "../evil" to "evil"', () => {
expect(sanitizeName('../evil')).toBe('evil');
});
it('should sanitize "../../etc/passwd" to "passwd"', () => {
expect(sanitizeName('../../etc/passwd')).toBe('passwd');
});
it('should sanitize "..\\evil" to "evil"', () => {
expect(sanitizeName('..\\evil')).toBe('evil');
});
it('should keep valid skill names unchanged', () => {
expect(sanitizeName('my-skill')).toBe('my-skill');
expect(sanitizeName('react-best-practices')).toBe('react-best-practices');
});
it('should produce a path inside installDir after sanitization', () => {
const evilName = '../evil';
const sanitized = sanitizeName(evilName);
const targetPath = normalize(join(installDir, sanitized));
expect(isPathInside(targetPath, installDir)).toBe(true);
expect(targetPath).toBe(join(installDir, 'evil'));
});
it('should detect unsanitized traversal names before normalization', () => {
const rawPath = `${installDir}/../evil`;
expect(isPathInside(rawPath, installDir)).toBe(false);
});
it('should ensure sanitization prevents the traversal entirely', () => {
const evilName = '../evil';
const sanitized = sanitizeName(evilName);
const targetPath = normalize(join(installDir, sanitized));
expect(targetPath).toBe(join(installDir, 'evil'));
expect(targetPath.startsWith(installDir)).toBe(true);
});
});
});
+39
View File
@@ -0,0 +1,39 @@
const SKILLKIT_LOGO_SVG_BASE64 =
'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0id2hpdGUiPjxyZWN0IHdpZHRoPSI2IiBoZWlnaHQ9IjYiIHg9IjEiIHk9IjEiLz48cmVjdCB3aWR0aD0iNiIgaGVpZ2h0PSI2IiB4PSI5IiB5PSIxIi8+PHJlY3Qgd2lkdGg9IjYiIGhlaWdodD0iNiIgeD0iMSIgeT0iOSIvPjxyZWN0IHdpZHRoPSI2IiBoZWlnaHQ9IjYiIHg9IjkiIHk9IjkiLz48L3N2Zz4=';
function encodeBadgeSegment(text: string): string {
return encodeURIComponent(text).replace(/-/g, '--');
}
export function generateBadge(skills: string[]): {
url: string;
markdown: string;
html: string;
} {
const count = skills.length;
if (count === 0) {
const url = `https://img.shields.io/badge/SkillKit-No%20Skills-555555?style=flat-square&logo=data:image/svg+xml;base64,${SKILLKIT_LOGO_SVG_BASE64}`;
return {
url,
markdown: `[![SkillKit Stack](${url})](https://agenstskills.com)`,
html: `<a href="https://agenstskills.com"><img src="${url}" alt="SkillKit Stack" /></a>`,
};
}
const maxDisplay = 5;
const displayNames = skills.slice(0, maxDisplay);
const suffix = count > maxDisplay ? ` +${count - maxDisplay} more` : '';
const label = `SkillKit ${count} skills`;
const message = displayNames.join(' | ') + suffix;
const encodedLabel = encodeBadgeSegment(label);
const encodedMessage = encodeBadgeSegment(message);
const url = `https://img.shields.io/badge/${encodedLabel}-${encodedMessage}-black?style=flat-square&logo=data:image/svg+xml;base64,${SKILLKIT_LOGO_SVG_BASE64}`;
return {
url,
markdown: `[![SkillKit Stack](${url})](https://agenstskills.com)`,
html: `<a href="https://agenstskills.com"><img src="${url}" alt="SkillKit Stack" /></a>`,
};
}
+41 -2
View File
@@ -8,6 +8,7 @@ import {
select,
header,
} from '../onboarding/index.js';
import { FederatedSearch, GitHubSkillRegistry, RateLimitError } from '@skillkit/core';
interface SkillResult {
name: string;
@@ -54,6 +55,10 @@ export class FindCommand extends Command {
description: 'Minimal output (just list skills)',
});
federated = Option.Boolean('--federated,-f', false, {
description: 'Search external registries (GitHub SKILL.md files)',
});
async execute(): Promise<number> {
const s = spinner();
const limit = parseInt(this.limit, 10) || 10;
@@ -128,12 +133,46 @@ export class FindCommand extends Command {
}
}
if (this.federated && this.query) {
s.start('Searching external registries...');
const fedSearch = new FederatedSearch();
fedSearch.addRegistry(new GitHubSkillRegistry());
try {
const fedResult = await fedSearch.search(this.query, { limit: parseInt(this.limit, 10) || 10 });
s.stop(`Found ${fedResult.total} external skill(s) from ${fedResult.registries.join(', ') || 'none'}`);
if (fedResult.skills.length > 0) {
console.log('');
console.log(colors.bold('External Skills (SKILL.md):'));
for (const skill of fedResult.skills) {
const stars = typeof skill.stars === 'number' ? colors.muted(` ★${skill.stars}`) : '';
const desc = skill.description
? colors.muted(` - ${skill.description.slice(0, 50)}${skill.description.length > 50 ? '...' : ''}`)
: '';
console.log(` ${colors.cyan(symbols.bullet)} ${colors.primary(skill.name)}${stars}${desc}`);
if (!this.quiet) {
console.log(` ${colors.muted(skill.source)}`);
}
}
console.log('');
}
} catch (err) {
if (err instanceof RateLimitError) {
s.stop(colors.warning('Rate limited by GitHub API'));
console.log(colors.muted('Set GITHUB_TOKEN env var or wait before retrying.'));
} else {
s.stop(colors.warning('Federated search failed'));
}
}
}
if (results.length === 0) {
console.log(colors.muted('No skills found matching your search'));
console.log('');
console.log(colors.muted('Try:'));
console.log(colors.muted(' skillkit find --top # Show featured skills'));
console.log(colors.muted(' skillkit ui # Browse in TUI'));
console.log(colors.muted(' skillkit find --top # Show featured skills'));
console.log(colors.muted(' skillkit find -f <query> # Search external registries'));
console.log(colors.muted(' skillkit ui # Browse in TUI'));
return 0;
}
+6
View File
@@ -108,3 +108,9 @@ export {
// Tree command for hierarchical skill browsing (Phase 21)
export { TreeCommand } from './tree.js';
// Quick setup (zero-friction entry)
export { QuickCommand } from './quick.js';
// SKILL.md ecosystem
export { SkillMdValidateCommand, SkillMdInitCommand, SkillMdCheckCommand } from './skillmd.js';
+375
View File
@@ -0,0 +1,375 @@
import { existsSync, mkdirSync, cpSync, rmSync, symlinkSync } from 'node:fs';
import { join, resolve, normalize } from 'node:path';
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
const execFileAsync = promisify(execFile);
import { Command } from 'clipanion';
import {
type ProjectProfile,
type SkillMetadata,
type AgentType,
ContextManager,
RecommendationEngine,
loadIndex as loadIndexFromCache,
isIndexStale,
buildSkillIndex,
saveIndex,
KNOWN_SKILL_REPOS,
isPathInside,
isLocalPath,
detectProvider,
} from '@skillkit/core';
import { getAdapter, detectAgent, getAllAdapters } from '@skillkit/agents';
import { getInstallDir, saveSkillMetadata } from '../helpers.js';
import {
welcome,
spinner,
step,
success,
error,
warn,
colors,
symbols,
confirm,
select,
outro,
formatAgent,
getAgentIcon,
isCancel,
cancel,
showProjectSummary,
progressBar,
formatQualityBadge,
saveLastAgents,
} from '../onboarding/index.js';
function truncate(str: string, maxLen: number): string {
if (str.length <= maxLen) return str;
return str.slice(0, maxLen - 3) + '...';
}
export class QuickCommand extends Command {
static override paths = [['quick']];
static override usage = Command.Usage({
description: 'Zero-friction skill setup: detect agents, analyze project, recommend and install',
examples: [
['Quick setup', '$0 quick'],
],
});
async execute(): Promise<number> {
const s = spinner();
try {
welcome();
step(`${colors.bold('Quick Setup')} - zero-friction skill installation`);
console.log('');
s.start('Detecting installed AI agents...');
const allAdapters = getAllAdapters();
const detectedAgents: AgentType[] = [];
for (const adapter of allAdapters) {
try {
const installDir = getInstallDir(false, adapter.type);
const globalDir = getInstallDir(true, adapter.type);
if (existsSync(installDir) || existsSync(globalDir) || existsSync(adapter.configFile)) {
detectedAgents.push(adapter.type);
}
} catch {
// skip
}
}
if (detectedAgents.length === 0) {
const fallback = await detectAgent();
detectedAgents.push(fallback);
}
s.stop(`Detected ${detectedAgents.length} agent${detectedAgents.length !== 1 ? 's' : ''}: ${detectedAgents.map(formatAgent).join(', ')}`);
s.start('Analyzing project...');
const targetPath = resolve(process.cwd());
const manager = new ContextManager(targetPath);
let context = manager.get();
if (!context) {
context = manager.init();
}
s.stop('Project analyzed');
if (!context) {
error('Failed to analyze project');
return 1;
}
const profile: ProjectProfile = {
name: context.project.name,
type: context.project.type,
stack: context.stack,
patterns: context.patterns,
installedSkills: context.skills?.installed || [],
excludedSkills: context.skills?.excluded || [],
};
const languages = profile.stack.languages.map((l: { name: string; version?: string }) => `${l.name}${l.version ? ` ${l.version}` : ''}`);
const frameworks = profile.stack.frameworks.map((f: { name: string; version?: string }) => `${f.name}${f.version ? ` ${f.version}` : ''}`);
showProjectSummary({
name: profile.name,
type: profile.type,
languages,
frameworks,
});
let index = loadIndexFromCache();
if (!index || index.skills.length === 0) {
s.start('Building skill index from known sources...');
try {
const result = await buildSkillIndex(KNOWN_SKILL_REPOS, (message: string) => {
s.message(message);
});
index = result.index;
saveIndex(index);
s.stop(`Indexed ${index.skills.length} skills`);
} catch {
s.stop(colors.error('Failed to build index'));
warn('Could not fetch skill index. Try running: skillkit recommend --update');
return 1;
}
} else if (isIndexStale(index)) {
step(colors.muted('Skill index is stale. Run "skillkit recommend --update" to refresh.'));
}
const engine = new RecommendationEngine();
engine.loadIndex(index);
const result = engine.recommend(profile, {
limit: 5,
minScore: 20,
excludeInstalled: true,
includeReasons: true,
});
const recommendations = result.recommendations;
if (recommendations.length === 0) {
warn('No matching skills found for your project.');
console.log(colors.muted('Try running: skillkit recommend --update'));
return 0;
}
console.log('');
console.log(colors.bold(`Top ${recommendations.length} Recommended Skills:`));
console.log('');
const options: Array<{ value: string; label: string; hint?: string }> = [];
for (let i = 0; i < recommendations.length; i++) {
const rec = recommendations[i];
let scoreColor: (text: string) => string;
if (rec.score >= 70) {
scoreColor = colors.success;
} else if (rec.score >= 50) {
scoreColor = colors.warning;
} else {
scoreColor = colors.muted;
}
const scoreBar = progressBar(rec.score, 100, 10);
const qualityScore = rec.skill.quality ?? null;
const qualityDisplay = typeof qualityScore === 'number' && Number.isFinite(qualityScore)
? ` ${formatQualityBadge(qualityScore)}`
: '';
console.log(` ${colors.bold(`${i + 1}.`)} ${scoreColor(`${rec.score}%`)} ${colors.dim(scoreBar)} ${colors.bold(rec.skill.name)}${qualityDisplay}`);
if (rec.skill.description) {
console.log(` ${colors.muted(truncate(rec.skill.description, 70))}`);
}
options.push({
value: `${i}`,
label: `${rec.skill.name} (${rec.score}% match)`,
hint: rec.skill.source || undefined,
});
}
console.log('');
const skipOption = { value: 'skip', label: 'Skip installation' };
const selectResult = await select({
message: 'Select a skill to install',
options: [...options, skipOption],
});
if (isCancel(selectResult) || selectResult === 'skip') {
cancel('Quick setup complete (no installation)');
return 0;
}
const selectedIndex = parseInt(selectResult as string, 10);
const selectedSkill = recommendations[selectedIndex];
if (!selectedSkill || !selectedSkill.skill.source) {
error('Selected skill has no installable source');
return 1;
}
const agentDisplay = detectedAgents.length <= 3
? detectedAgents.map(formatAgent).join(', ')
: `${detectedAgents.slice(0, 2).map(formatAgent).join(', ')} +${detectedAgents.length - 2} more`;
const confirmResult = await confirm({
message: `Install ${colors.bold(selectedSkill.skill.name)} to ${agentDisplay}?`,
initialValue: true,
});
if (isCancel(confirmResult) || !confirmResult) {
cancel('Installation cancelled');
return 0;
}
saveLastAgents(detectedAgents);
const providerAdapter = detectProvider(selectedSkill.skill.source);
if (!providerAdapter) {
error(`Could not detect provider for: ${selectedSkill.skill.source}`);
return 1;
}
s.start(`Fetching ${selectedSkill.skill.name}...`);
const cloneResult = await providerAdapter.clone(selectedSkill.skill.source, '', { depth: 1 });
if (!cloneResult.success || !cloneResult.path) {
s.stop(colors.error(cloneResult.error || 'Failed to fetch source'));
return 1;
}
const discoveredSkills = cloneResult.discoveredSkills || [];
const matchedSkill = discoveredSkills.find(ds => ds.name === selectedSkill.skill.name) || discoveredSkills[0];
if (!matchedSkill) {
s.stop(colors.error('Skill not found in repository'));
return 1;
}
s.stop(`Found ${selectedSkill.skill.name}`);
let primaryPath: string | null = null;
const installedAgents: string[] = [];
for (const agentType of detectedAgents) {
const adapter = getAdapter(agentType);
const installDir = getInstallDir(false, agentType);
if (!existsSync(installDir)) {
mkdirSync(installDir, { recursive: true });
}
const sanitizedName = matchedSkill.name.split(/[/\\]/).pop() || matchedSkill.name;
const targetInstallPath = normalize(join(installDir, sanitizedName));
if (!isPathInside(targetInstallPath, installDir)) {
error(`Skipping ${matchedSkill.name} for ${adapter.name} (install path escapes target directory)`);
continue;
}
const securityRoot = cloneResult.tempRoot || cloneResult.path;
if (!isPathInside(matchedSkill.path, securityRoot)) {
error(`Skipping ${matchedSkill.name} for ${adapter.name} (path traversal detected)`);
continue;
}
const useSymlink = detectedAgents.length > 1 && primaryPath !== null;
s.start(`Installing to ${adapter.name}${useSymlink ? ' (symlink)' : ''}...`);
try {
if (existsSync(targetInstallPath)) {
rmSync(targetInstallPath, { recursive: true, force: true });
}
if (useSymlink && primaryPath) {
symlinkSync(primaryPath, targetInstallPath, 'dir');
} else {
cpSync(matchedSkill.path, targetInstallPath, { recursive: true, dereference: true });
if (detectedAgents.length > 1 && primaryPath === null) {
primaryPath = targetInstallPath;
}
const packageJsonPath = join(targetInstallPath, 'package.json');
if (existsSync(packageJsonPath)) {
s.stop(`Installed to ${adapter.name}`);
s.start('Installing npm dependencies...');
try {
await execFileAsync('npm', ['install', '--production'], { cwd: targetInstallPath });
s.stop('Dependencies installed');
} catch {
s.stop(colors.warning('Dependencies failed'));
console.log(colors.muted('Run manually: npm install in ' + targetInstallPath));
}
s.start('Finishing installation...');
}
}
const metadata: SkillMetadata = {
name: matchedSkill.name,
description: selectedSkill.skill.description || '',
source: selectedSkill.skill.source,
sourceType: providerAdapter.type,
subpath: matchedSkill.name,
installedAt: new Date().toISOString(),
enabled: true,
};
saveSkillMetadata(targetInstallPath, metadata);
installedAgents.push(agentType);
s.stop(`Installed to ${adapter.name}${useSymlink ? ' (symlink)' : ''}`);
} catch (err) {
s.stop(colors.error(`Failed to install to ${adapter.name}`));
console.log(colors.muted(err instanceof Error ? err.message : String(err)));
}
}
const cleanupPath = cloneResult.tempRoot || cloneResult.path;
if (!isLocalPath(selectedSkill.skill.source) && cleanupPath && existsSync(cleanupPath)) {
rmSync(cleanupPath, { recursive: true, force: true });
}
if (installedAgents.length > 0) {
console.log('');
success(`Installed ${colors.bold(matchedSkill.name)} to ${installedAgents.length} agent${installedAgents.length !== 1 ? 's' : ''}`);
for (const a of installedAgents) {
console.log(colors.muted(` ${symbols.success} ${getAgentIcon(a)} ${formatAgent(a)}`));
}
console.log('');
const badgeUrl = `https://img.shields.io/badge/SkillKit-${encodeURIComponent(matchedSkill.name)}-black?style=flat-square`;
console.log(colors.dim('Add to your README:'));
console.log(colors.muted(` [![SkillKit](${badgeUrl})](https://agenstskills.com)`));
outro('Quick setup complete!');
console.log('');
console.log(colors.muted('Next steps:'));
console.log(colors.muted(` ${symbols.arrowRight} Run ${colors.cyan('skillkit sync')} to update agent configs`));
console.log(colors.muted(` ${symbols.arrowRight} Run ${colors.cyan('skillkit recommend')} for more suggestions`));
console.log(colors.muted(` ${symbols.arrowRight} Run ${colors.cyan('skillkit list')} to see installed skills`));
console.log('');
} else {
warn('No agents were installed');
}
return 0;
} catch (err) {
s.stop(colors.error('Quick setup failed'));
console.log(colors.muted(err instanceof Error ? err.message : String(err)));
return 1;
}
}
}
+162
View File
@@ -52,6 +52,9 @@ export class RecommendCommand extends Command {
['Update skill index', '$0 recommend --update'],
['Search for skills by task', '$0 recommend --task "authentication"'],
['Search for skills (alias)', '$0 recommend --search "testing"'],
['Hybrid search (vector + keyword)', '$0 recommend --search "auth" --hybrid'],
['Hybrid search with query expansion', '$0 recommend --search "auth" --hybrid --expand'],
['Build hybrid search index', '$0 recommend --build-index'],
],
});
@@ -125,6 +128,26 @@ export class RecommendCommand extends Command {
description: 'Show category path for each recommendation',
});
// Hybrid search mode
hybrid = Option.Boolean('--hybrid,-H', false, {
description: 'Use hybrid search (vector + keyword)',
});
// Query expansion
expand = Option.Boolean('--expand,-x', false, {
description: 'Enable query expansion (requires --hybrid)',
});
// Reranking
rerank = Option.Boolean('--rerank', false, {
description: 'Enable LLM reranking (requires --hybrid)',
});
// Build index
buildIndex = Option.Boolean('--build-index', false, {
description: 'Build/rebuild the hybrid search embedding index',
});
async execute(): Promise<number> {
const targetPath = resolve(this.projectPath || process.cwd());
@@ -133,6 +156,16 @@ export class RecommendCommand extends Command {
return await this.updateIndex();
}
// Handle hybrid index building
if (this.buildIndex) {
return await this.buildHybridIndex();
}
// Validate hybrid-dependent options
if ((this.expand || this.rerank) && !this.hybrid) {
warn('--expand and --rerank require --hybrid flag. These options will be ignored.');
}
if (!this.quiet && !this.json) {
header('Skill Recommendations');
}
@@ -168,6 +201,9 @@ export class RecommendCommand extends Command {
// Handle search mode (--search or --task)
const searchQuery = this.search || this.task;
if (searchQuery) {
if (this.hybrid) {
return await this.handleHybridSearch(engine, searchQuery);
}
return this.handleSearch(engine, searchQuery);
}
@@ -446,6 +482,132 @@ export class RecommendCommand extends Command {
console.log(colors.muted('More details: skillkit recommend --explain --verbose'));
}
private async handleHybridSearch(engine: RecommendationEngine, query: string): Promise<number> {
if (!this.quiet && !this.json) {
header(`Hybrid Search: "${query}"`);
}
const s = !this.quiet && !this.json ? spinner() : null;
s?.start('Initializing hybrid search...');
try {
await engine.initHybridSearch();
s?.message('Searching...');
const results = await engine.hybridSearch({
query,
limit: this.limit ? parseInt(this.limit, 10) : 10,
hybrid: true,
enableExpansion: this.expand,
enableReranking: this.rerank,
filters: {
minScore: this.minScore ? parseInt(this.minScore, 10) : undefined,
},
});
s?.stop(`Found ${results.length} results`);
if (this.json) {
console.log(JSON.stringify(results, null, 2));
return 0;
}
if (results.length === 0) {
warn(`No skills found matching "${query}"`);
return 0;
}
console.log('');
console.log(colors.bold(`Hybrid search results for "${query}" (${results.length} found):`));
if (this.expand && results[0]?.expandedTerms?.length) {
console.log(colors.muted(` Expanded: ${results[0].expandedTerms.join(', ')}`));
}
console.log('');
for (const result of results) {
let relevanceColor: (text: string) => string;
if (result.relevance >= 70) {
relevanceColor = colors.success;
} else if (result.relevance >= 50) {
relevanceColor = colors.warning;
} else {
relevanceColor = colors.muted;
}
const relevanceBar = progressBar(result.relevance, 100, 10);
console.log(` ${relevanceColor(`${result.relevance}%`)} ${colors.dim(relevanceBar)} ${colors.bold(result.skill.name)}`);
if (result.skill.description) {
console.log(` ${colors.muted(truncate(result.skill.description, 70))}`);
}
if (this.verbose) {
const scores: string[] = [];
if (typeof result.vectorSimilarity === 'number') {
scores.push(`vector: ${(result.vectorSimilarity * 100).toFixed(0)}%`);
}
if (typeof result.keywordScore === 'number') {
scores.push(`keyword: ${result.keywordScore.toFixed(0)}%`);
}
if (typeof result.rrfScore === 'number') {
scores.push(`rrf: ${result.rrfScore.toFixed(3)}`);
}
if (scores.length > 0) {
console.log(` ${colors.dim('Scores:')} ${scores.join(' | ')}`);
}
}
if (result.matchedTerms.length > 0) {
console.log(` ${colors.dim('Matched:')} ${result.matchedTerms.join(', ')}`);
}
console.log('');
}
return 0;
} catch (err) {
s?.stop(colors.error('Hybrid search failed'));
console.log(colors.muted(err instanceof Error ? err.message : String(err)));
console.log(colors.muted('Falling back to standard search...'));
return this.handleSearch(engine, query);
}
}
private async buildHybridIndex(): Promise<number> {
if (!this.quiet) {
header('Build Hybrid Search Index');
}
const index = this.loadIndex();
if (!index || index.skills.length === 0) {
warn('No skill index found. Run --update first.');
return 1;
}
const s = spinner();
s.start('Initializing...');
try {
const engine = new RecommendationEngine();
engine.loadIndex(index);
await engine.buildHybridIndex((progress) => {
const percentage = Math.round((progress.current / progress.total) * 100);
s.message(`${progress.phase}: ${progress.message || ''} (${percentage}%)`);
});
s.stop(colors.success(`${symbols.success} Built hybrid index for ${index.skills.length} skills`));
console.log(colors.muted(' Index stored in: ~/.skillkit/search.db'));
console.log(colors.muted(' Use --hybrid flag for vector+keyword search\n'));
return 0;
} catch (err) {
s.stop(colors.error('Failed to build hybrid index'));
console.log(colors.muted(err instanceof Error ? err.message : String(err)));
return 1;
}
}
private handleSearch(engine: RecommendationEngine, query: string): number {
if (!this.quiet && !this.json) {
header(`Search: "${query}"`);
+440
View File
@@ -0,0 +1,440 @@
import { existsSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
import { join, resolve, basename, relative } from 'node:path';
import { Command, Option } from 'clipanion';
import {
colors,
symbols,
spinner,
step,
success,
error,
warn,
header,
} from '../onboarding/index.js';
interface SkillMdValidation {
path: string;
exists: boolean;
hasName: boolean;
hasDescription: boolean;
hasTriggers: boolean;
hasCapabilities: boolean;
triggerCount: number;
capabilityCount: number;
score: number;
issues: string[];
}
function validateSkillMd(filePath: string): SkillMdValidation {
const result: SkillMdValidation = {
path: filePath,
exists: false,
hasName: false,
hasDescription: false,
hasTriggers: false,
hasCapabilities: false,
triggerCount: 0,
capabilityCount: 0,
score: 0,
issues: [],
};
if (!existsSync(filePath)) {
result.issues.push('File does not exist');
return result;
}
result.exists = true;
const content = readFileSync(filePath, 'utf-8');
if (!content.trim()) {
result.issues.push('File is empty');
return result;
}
const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
const bodyContent = frontmatterMatch
? content.slice(frontmatterMatch[0].length)
: content;
if (frontmatterMatch) {
const frontmatter = frontmatterMatch[1];
if (/^name:\s*.+$/m.test(frontmatter)) result.hasName = true;
if (/^description:\s*.+$/m.test(frontmatter)) result.hasDescription = true;
}
if (!result.hasName) {
if (/^#\s+.+$/m.test(bodyContent)) result.hasName = true;
}
if (!result.hasDescription) {
if (/^##?\s*(description|about|overview)\b/im.test(bodyContent)) {
result.hasDescription = true;
} else {
const lines = bodyContent.split(/\r?\n/).filter(l => l.trim());
const nonHeaderLines = lines.filter(l => !l.startsWith('#'));
if (nonHeaderLines.length >= 2) result.hasDescription = true;
}
}
const triggerPatterns = [
/triggers?\s*when/i,
/when\s*to\s*use/i,
/use\s*this\s*when/i,
/\*\*triggers?\b/i,
/^[-*]\s+.+(when|if|pattern|trigger)/im,
/glob:/i,
];
for (const pattern of triggerPatterns) {
if (pattern.test(content)) {
result.hasTriggers = true;
break;
}
}
if (result.hasTriggers) {
const triggerSection = content.match(/triggers?\s*when[:\s]*\n((?:[-*]\s+.+\n?)+)/i);
result.triggerCount = triggerSection
? (triggerSection[1].match(/^[-*]\s+/gm) || []).length
: 1;
}
const capabilityPatterns = [
/capabilities?[:\s]/i,
/features?[:\s]/i,
/what\s*(it|this)\s*(does|can)/i,
/^##?\s*capabilities/im,
/^##?\s*features/im,
];
for (const pattern of capabilityPatterns) {
if (pattern.test(content)) {
result.hasCapabilities = true;
break;
}
}
if (result.hasCapabilities) {
const capSection = content.match(/(?:capabilities?|features?)[:\s]*\n((?:[-*]\s+.+\n?)+)/i);
result.capabilityCount = capSection
? (capSection[1].match(/^[-*]\s+/gm) || []).length
: 1;
}
if (!result.hasName) result.issues.push('Missing name field');
if (!result.hasDescription) result.issues.push('Missing description section');
if (!result.hasTriggers) result.issues.push('No trigger patterns found');
if (!result.hasCapabilities) result.issues.push('No capabilities list found');
let score = 0;
if (result.exists) score += 10;
if (result.hasName) score += 20;
if (result.hasDescription) score += 25;
if (result.hasTriggers) score += 20;
if (result.hasCapabilities) score += 15;
if (result.triggerCount >= 3) score += 5;
if (result.capabilityCount >= 3) score += 5;
if (frontmatterMatch) {
const fm = frontmatterMatch[1];
if (/^version:/m.test(fm)) score += 3;
if (/^license:/m.test(fm)) score += 2;
if (/^tags:/m.test(fm)) score += 3;
if (/^metadata:/m.test(fm)) score += 2;
}
result.score = Math.min(100, score);
return result;
}
function printValidation(validation: SkillMdValidation, verbose = false): void {
const scoreColor = validation.score >= 80
? colors.success
: validation.score >= 60
? colors.warning
: colors.error;
console.log(` ${colors.muted('Score:')} ${scoreColor(`${validation.score}`)}/100`);
console.log(` ${validation.hasName ? colors.success(symbols.success) : colors.error(symbols.error)} Name field`);
console.log(` ${validation.hasDescription ? colors.success(symbols.success) : colors.error(symbols.error)} Description section`);
console.log(` ${validation.hasTriggers ? colors.success(symbols.success) : colors.error(symbols.error)} Trigger patterns${validation.triggerCount > 0 ? ` (${validation.triggerCount})` : ''}`);
console.log(` ${validation.hasCapabilities ? colors.success(symbols.success) : colors.error(symbols.error)} Capabilities list${validation.capabilityCount > 0 ? ` (${validation.capabilityCount})` : ''}`);
if (verbose && validation.issues.length > 0) {
console.log('');
console.log(` ${colors.warning('Issues:')}`);
for (const issue of validation.issues) {
console.log(` ${colors.warning(symbols.warning)} ${issue}`);
}
}
}
export class SkillMdValidateCommand extends Command {
static override paths = [['skillmd', 'validate'], ['skill-md', 'validate']];
static override usage = Command.Usage({
description: 'Validate a SKILL.md file against the standard',
examples: [
['Validate SKILL.md in current directory', '$0 skillmd validate'],
['Validate specific file', '$0 skillmd validate ./path/to/SKILL.md'],
],
});
targetPath = Option.String({ required: false, name: 'path' });
verbose = Option.Boolean('--verbose,-v', false, {
description: 'Show detailed validation results',
});
json = Option.Boolean('--json', false, {
description: 'Output as JSON',
});
async execute(): Promise<number> {
const targetPath = this.targetPath || join(process.cwd(), 'SKILL.md');
const resolvedPath = resolve(targetPath);
const filePath = resolvedPath.endsWith('SKILL.md') ? resolvedPath : join(resolvedPath, 'SKILL.md');
if (!this.json) {
header('SKILL.md Validation');
step(`Validating: ${colors.cyan(filePath)}`);
console.log('');
}
const validation = validateSkillMd(filePath);
if (this.json) {
console.log(JSON.stringify(validation, null, 2));
return validation.score >= 60 ? 0 : 1;
}
console.log(colors.primary(basename(filePath)));
printValidation(validation, this.verbose);
console.log('');
if (validation.score >= 80) {
success(`SKILL.md is compliant (score: ${validation.score}/100)`);
} else if (validation.score >= 60) {
warn(`SKILL.md needs improvement (score: ${validation.score}/100)`);
} else {
error(`SKILL.md does not meet minimum standard (score: ${validation.score}/100)`);
}
return validation.score >= 60 ? 0 : 1;
}
}
export class SkillMdInitCommand extends Command {
static override paths = [['skillmd', 'init'], ['skill-md', 'init']];
static override usage = Command.Usage({
description: 'Create a template SKILL.md in the current directory',
examples: [
['Create SKILL.md template', '$0 skillmd init'],
['Create with custom name', '$0 skillmd init --name my-skill'],
],
});
name = Option.String('--name,-n', {
description: 'Skill name',
});
force = Option.Boolean('--force,-f', false, {
description: 'Overwrite existing SKILL.md',
});
async execute(): Promise<number> {
const outputPath = join(process.cwd(), 'SKILL.md');
if (existsSync(outputPath) && !this.force) {
warn('SKILL.md already exists');
console.log(colors.muted('Use --force to overwrite'));
return 1;
}
const skillName = this.name || basename(process.cwd());
const formattedName = skillName
.split('-')
.map((w: string) => w.charAt(0).toUpperCase() + w.slice(1))
.join(' ');
const template = [
'---',
`name: ${skillName}`,
'description: What this skill does and when to use it',
'version: "1.0"',
'license: MIT',
'tags: [general]',
'metadata:',
' author: your-name',
'---',
'',
`# ${formattedName}`,
'',
'Brief description of what this skill provides to AI coding agents.',
'',
'## Triggers when:',
`- User asks about ${skillName} related tasks`,
`- Project contains ${skillName} configuration files`,
`- Code changes involve ${skillName} patterns`,
'',
'## Capabilities:',
`- Provides best practices for ${skillName}`,
'- Generates boilerplate code and configurations',
'- Validates existing implementations',
'- Suggests improvements and optimizations',
'',
'## Steps',
'1. First step the AI agent should take',
'2. Second step with specific instructions',
'3. Third step with expected outcome',
'',
'## Examples',
'',
'```',
'Example code or configuration here',
'```',
'',
].join('\n');
writeFileSync(outputPath, template);
success(`Created SKILL.md for "${skillName}"`);
console.log('');
console.log(colors.muted('Next steps:'));
console.log(` ${colors.cyan('1.')} Edit SKILL.md with your skill instructions`);
console.log(` ${colors.cyan('2.')} Run ${colors.cyan('skillkit skillmd validate')} to check compliance`);
console.log(` ${colors.cyan('3.')} Run ${colors.cyan('skillkit publish submit')} to share with the marketplace`);
return 0;
}
}
export class SkillMdCheckCommand extends Command {
static override paths = [['skillmd', 'check'], ['skill-md', 'check']];
static override usage = Command.Usage({
description: 'Check all SKILL.md files in the project for compliance',
examples: [
['Check current directory', '$0 skillmd check'],
['Check specific directory', '$0 skillmd check ./skills'],
],
});
targetPath = Option.String({ required: false, name: 'path' });
verbose = Option.Boolean('--verbose,-v', false, {
description: 'Show detailed validation results',
});
async execute(): Promise<number> {
const targetPath = resolve(this.targetPath || process.cwd());
header('SKILL.md Compliance Check');
const s = spinner();
s.start('Scanning for SKILL.md files...');
const skillMdFiles = this.findSkillMdFiles(targetPath);
s.stop(`Found ${skillMdFiles.length} SKILL.md file(s)`);
if (skillMdFiles.length === 0) {
warn('No SKILL.md files found');
console.log(colors.muted(`Searched: ${targetPath}`));
console.log('');
console.log(colors.muted('Create one with:'));
console.log(` ${colors.cyan('skillkit skillmd init')}`);
return 0;
}
const validations: SkillMdValidation[] = skillMdFiles.map(f => validateSkillMd(f));
validations.sort((a, b) => b.score - a.score);
console.log('');
for (const validation of validations) {
const relativePath = relative(targetPath, validation.path);
const scoreColor = validation.score >= 80 ? colors.success : validation.score >= 60 ? colors.warning : colors.error;
console.log(`${scoreColor(symbols.bullet)} ${colors.primary(relativePath)} ${colors.muted(`(${validation.score}/100)`)}`);
if (this.verbose) {
printValidation(validation, true);
console.log('');
}
}
console.log('');
const passing = validations.filter(v => v.score >= 60).length;
const failing = validations.filter(v => v.score < 60).length;
const avgScore = Math.round(validations.reduce((sum, v) => sum + v.score, 0) / validations.length);
console.log(colors.muted('Summary:'));
console.log(` ${colors.muted('Total:')} ${validations.length}`);
console.log(` ${colors.success(symbols.success)} Passing (60+): ${passing}`);
if (failing > 0) {
console.log(` ${colors.error(symbols.error)} Failing: ${failing}`);
}
console.log(` ${colors.muted('Average score:')} ${avgScore}/100`);
console.log('');
if (failing > 0) {
error(`${failing} SKILL.md file(s) below minimum standard`);
return 1;
}
success('All SKILL.md files are compliant');
return 0;
}
private findSkillMdFiles(dir: string): string[] {
const results: string[] = [];
const directFile = join(dir, 'SKILL.md');
if (existsSync(directFile)) results.push(directFile);
const searchDirs = [
join(dir, 'skills'),
join(dir, '.claude', 'skills'),
join(dir, '.cursor', 'skills'),
join(dir, '.codex', 'skills'),
join(dir, '.github', 'skills'),
];
for (const searchDir of searchDirs) {
if (!existsSync(searchDir)) continue;
this.scanDir(searchDir, results, 0);
}
try {
const entries = readdirSync(dir, { withFileTypes: true });
for (const entry of entries) {
if (!entry.isDirectory()) continue;
if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
const entrySkillMd = join(dir, entry.name, 'SKILL.md');
if (existsSync(entrySkillMd) && !results.includes(entrySkillMd)) {
results.push(entrySkillMd);
}
}
} catch {
// ignore read errors
}
return results;
}
private scanDir(dir: string, results: string[], depth: number): void {
if (depth > 3) return;
try {
const entries = readdirSync(dir, { withFileTypes: true });
for (const entry of entries) {
const entryPath = join(dir, entry.name);
if (entry.isFile() && entry.name === 'SKILL.md') {
if (!results.includes(entryPath)) results.push(entryPath);
}
if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
this.scanDir(entryPath, results, depth + 1);
}
}
} catch {
// ignore read errors
}
}
}
+11 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/core",
"version": "1.9.0",
"version": "1.11.0",
"description": "Core functionality for SkillKit - skill discovery, parsing, and translation",
"type": "module",
"main": "./dist/index.js",
@@ -37,6 +37,10 @@
"./learning": {
"import": "./dist/learning/index.js",
"types": "./dist/learning/index.d.ts"
},
"./search": {
"import": "./dist/search/index.js",
"types": "./dist/search/index.d.ts"
}
},
"files": [
@@ -53,7 +57,13 @@
"yaml": "^2.6.1",
"zod": "^3.24.1"
},
"optionalDependencies": {
"node-llama-cpp": "^3.15.0",
"better-sqlite3": "^12.0.0",
"sqlite-vec": "^0.1.6"
},
"devDependencies": {
"@types/better-sqlite3": "^7.6.11",
"@types/node": "^22.10.5",
"tsup": "^8.3.5",
"typescript": "^5.7.2",
+6
View File
@@ -101,3 +101,9 @@ export * from './connectors/index.js';
// Execution Flow (Step Tracking & Metrics - Phase 21)
export * from './execution/index.js';
// Hybrid Search (QMD-Inspired Vector + Keyword Search)
export * from './search/index.js';
// Federated Registry (External Skill Sources)
export * from './registry/index.js';
+91
View File
@@ -11,8 +11,11 @@ import type {
SearchOptions,
SearchResult,
FreshnessResult,
RecommendHybridSearchOptions,
RecommendHybridSearchResult,
} from './types.js';
import { DEFAULT_SCORING_WEIGHTS, TAG_TO_TECH, getTechTags } from './types.js';
import type { HybridSearchPipeline } from '../search/hybrid.js';
/**
* Recommendation engine for matching skills to project profiles
@@ -20,16 +23,39 @@ import { DEFAULT_SCORING_WEIGHTS, TAG_TO_TECH, getTechTags } from './types.js';
export class RecommendationEngine {
private weights: ScoringWeights;
private index: SkillIndex | null = null;
private hybridPipeline: HybridSearchPipeline | null = null;
constructor(weights?: Partial<ScoringWeights>) {
this.weights = { ...DEFAULT_SCORING_WEIGHTS, ...weights };
}
/**
* Initialize hybrid search pipeline for vector + keyword search
*/
async initHybridSearch(): Promise<void> {
const { createHybridSearchPipeline } = await import('../search/hybrid.js');
this.hybridPipeline = createHybridSearchPipeline();
if (this.index) {
this.hybridPipeline.loadSkillsIndex(this.index);
}
await this.hybridPipeline.initialize();
}
/**
* Check if hybrid search is available
*/
isHybridSearchAvailable(): boolean {
return this.hybridPipeline !== null && this.hybridPipeline.isInitialized();
}
/**
* Load skill index from cache or generate from local skills
*/
loadIndex(index: SkillIndex): void {
this.index = index;
if (this.hybridPipeline) {
this.hybridPipeline.loadSkillsIndex(index);
}
}
/**
@@ -603,6 +629,71 @@ export class RecommendationEngine {
return { relevance, matchedTerms, snippet };
}
/**
* Hybrid search combining vector embeddings and keyword matching
*/
async hybridSearch(options: RecommendHybridSearchOptions): Promise<RecommendHybridSearchResult[]> {
const { query, limit = 10, hybrid = true, enableExpansion = false, enableReranking = false, filters } = options;
if (!hybrid || !this.hybridPipeline) {
const basicResults = this.search({ query, limit, semantic: true, filters });
return basicResults.map((r) => ({
...r,
hybridScore: r.relevance / 100,
}));
}
const response = await this.hybridPipeline.search({
query,
limit,
enableExpansion,
enableReranking,
});
let results = response.results.map((r) => ({
skill: r.skill,
relevance: r.relevance,
matchedTerms: r.matchedTerms,
snippet: r.snippet,
hybridScore: r.hybridScore,
vectorSimilarity: r.vectorSimilarity,
keywordScore: r.keywordScore,
rrfScore: r.rrfScore,
expandedTerms: r.expandedTerms,
}));
if (filters?.tags && filters.tags.length > 0) {
results = results.filter((r) =>
r.skill.tags?.some((t) => filters.tags!.includes(t))
);
}
if (filters?.verified) {
results = results.filter((r) => r.skill.verified);
}
if (filters?.minScore) {
results = results.filter((r) => r.relevance >= filters.minScore!);
}
return results.slice(0, limit);
}
/**
* Build hybrid search index from skills
*/
async buildHybridIndex(
onProgress?: (progress: { phase: string; current: number; total: number; message?: string }) => void
): Promise<void> {
if (!this.index) {
throw new Error('No skill index loaded. Call loadIndex() first.');
}
if (!this.hybridPipeline) {
await this.initHybridSearch();
}
await this.hybridPipeline!.buildIndex(this.index.skills, onProgress);
}
/**
* Check freshness of installed skills against project dependencies
*
+22
View File
@@ -326,3 +326,25 @@ export interface ReasoningRecommendationResult extends RecommendationResult {
strategy: string;
};
}
/**
* Hybrid search options for RecommendationEngine
*/
export interface RecommendHybridSearchOptions extends SearchOptions {
hybrid?: boolean;
enableExpansion?: boolean;
enableReranking?: boolean;
semanticWeight?: number;
keywordWeight?: number;
}
/**
* Hybrid search result with additional metadata for RecommendationEngine
*/
export interface RecommendHybridSearchResult extends SearchResult {
hybridScore?: number;
vectorSimilarity?: number;
keywordScore?: number;
rrfScore?: number;
expandedTerms?: string[];
}
+163
View File
@@ -0,0 +1,163 @@
export interface ExternalSkill {
name: string;
description: string;
source: string;
registry: string;
path?: string;
stars?: number;
updatedAt?: string;
}
export interface ExternalRegistry {
name: string;
search(query: string, options?: { limit?: number; timeoutMs?: number }): Promise<ExternalSkill[]>;
}
export interface FederatedResult {
skills: ExternalSkill[];
registries: string[];
total: number;
query: string;
}
export class RateLimitError extends Error {
constructor(registry: string) {
super(`Rate limited by ${registry} API. Authenticate with a token or wait before retrying.`);
this.name = 'RateLimitError';
}
}
export class GitHubSkillRegistry implements ExternalRegistry {
name = 'github';
private baseUrl = 'https://api.github.com';
async search(query: string, options?: { limit?: number; timeoutMs?: number }): Promise<ExternalSkill[]> {
const limit = options?.limit ?? 20;
const timeoutMs = options?.timeoutMs ?? 10_000;
const searchQuery = `SKILL.md ${query} in:path,file`;
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeoutMs);
try {
const headers: Record<string, string> = {
Accept: 'application/vnd.github.v3+json',
'User-Agent': 'skillkit-cli',
};
const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
if (token) {
headers.Authorization = `Bearer ${token}`;
}
const response = await fetch(
`${this.baseUrl}/search/code?q=${encodeURIComponent(searchQuery)}&per_page=${limit}`,
{
headers,
signal: controller.signal,
},
);
clearTimeout(timer);
if (!response.ok) {
if (response.status === 403) {
throw new RateLimitError(this.name);
}
return [];
}
const data = (await response.json()) as {
items?: Array<{
repository: {
full_name: string;
description?: string;
html_url: string;
stargazers_count?: number;
updated_at?: string;
};
path: string;
name: string;
}>;
};
if (!data.items) return [];
const seen = new Set<string>();
const skills: ExternalSkill[] = [];
for (const item of data.items) {
const repo = item.repository.full_name;
if (seen.has(repo)) continue;
seen.add(repo);
const pathParts = item.path.split('/');
const skillName =
pathParts.length > 1
? pathParts[pathParts.length - 2]
: repo.split('/').pop() || repo;
skills.push({
name: skillName,
description: item.repository.description || '',
source: item.repository.html_url,
registry: this.name,
path: item.path,
stars: item.repository.stargazers_count,
updatedAt: item.repository.updated_at,
});
}
return skills;
} catch (err) {
clearTimeout(timer);
if (err instanceof RateLimitError) throw err;
return [];
}
}
}
export class FederatedSearch {
private registries: ExternalRegistry[] = [];
addRegistry(registry: ExternalRegistry): void {
this.registries.push(registry);
}
async search(query: string, options?: { limit?: number }): Promise<FederatedResult> {
const limit = options?.limit ?? 20;
const results = await Promise.allSettled(
this.registries.map((r) => r.search(query, { limit })),
);
const allSkills: ExternalSkill[] = [];
const activeRegistries: string[] = [];
for (let i = 0; i < results.length; i++) {
const result = results[i];
if (result.status === 'fulfilled' && result.value.length > 0) {
allSkills.push(...result.value);
activeRegistries.push(this.registries[i].name);
} else if (result.status === 'rejected' && result.reason instanceof RateLimitError) {
throw result.reason;
}
}
const seen = new Set<string>();
const deduplicated: ExternalSkill[] = [];
for (const skill of allSkills) {
const key = `${skill.source}:${skill.name}`;
if (!seen.has(key)) {
seen.add(key);
deduplicated.push(skill);
}
}
deduplicated.sort((a, b) => (b.stars ?? 0) - (a.stars ?? 0));
return {
skills: deduplicated.slice(0, limit),
registries: activeRegistries,
total: deduplicated.length,
query,
};
}
}
@@ -0,0 +1,217 @@
import { describe, it, expect, beforeEach } from 'vitest';
import { EmbeddingService } from '../embeddings.js';
import type { SkillSummary } from '../../recommend/types.js';
describe('EmbeddingService', () => {
describe('cosineSimilarity', () => {
let service: EmbeddingService;
beforeEach(() => {
service = new EmbeddingService();
});
it('should return 1 for identical vectors', () => {
const a = new Float32Array([1, 0, 0]);
const b = new Float32Array([1, 0, 0]);
const similarity = service.cosineSimilarity(a, b);
expect(similarity).toBeCloseTo(1, 5);
});
it('should return 0 for orthogonal vectors', () => {
const a = new Float32Array([1, 0, 0]);
const b = new Float32Array([0, 1, 0]);
const similarity = service.cosineSimilarity(a, b);
expect(similarity).toBeCloseTo(0, 5);
});
it('should return -1 for opposite vectors', () => {
const a = new Float32Array([1, 0, 0]);
const b = new Float32Array([-1, 0, 0]);
const similarity = service.cosineSimilarity(a, b);
expect(similarity).toBeCloseTo(-1, 5);
});
it('should handle normalized vectors', () => {
const a = new Float32Array([0.5, 0.5, 0.5, 0.5]);
const b = new Float32Array([0.5, 0.5, 0.5, 0.5]);
const similarity = service.cosineSimilarity(a, b);
expect(similarity).toBeCloseTo(1, 5);
});
it('should throw for mismatched dimensions', () => {
const a = new Float32Array([1, 0]);
const b = new Float32Array([1, 0, 0]);
expect(() => service.cosineSimilarity(a, b)).toThrow('Vector dimensions mismatch');
});
it('should return 0 for zero vectors', () => {
const a = new Float32Array([0, 0, 0]);
const b = new Float32Array([1, 0, 0]);
const similarity = service.cosineSimilarity(a, b);
expect(similarity).toBe(0);
});
});
describe('initialization state', () => {
it('should not be initialized by default', () => {
const service = new EmbeddingService();
expect(service.isInitialized()).toBe(false);
});
it('should return default dimensions', () => {
const service = new EmbeddingService();
expect(service.getDimensions()).toBe(768);
});
});
describe('skill text building', () => {
it('should handle skill with all fields', async () => {
const service = new EmbeddingService();
const skill: SkillSummary = {
name: 'test-skill',
description: 'A test skill',
tags: ['tag1', 'tag2'],
compatibility: {
frameworks: ['react'],
languages: ['typescript'],
libraries: ['lodash'],
},
popularity: 100,
quality: 80,
verified: true,
};
const buildSkillText = (s: SkillSummary): string => {
const parts: string[] = [s.name];
if (s.description) parts.push(s.description);
if (s.tags?.length) parts.push(s.tags.join(' '));
if (s.compatibility?.frameworks?.length) parts.push(s.compatibility.frameworks.join(' '));
if (s.compatibility?.languages?.length) parts.push(s.compatibility.languages.join(' '));
if (s.compatibility?.libraries?.length) parts.push(s.compatibility.libraries.join(' '));
return parts.join(' ').toLowerCase();
};
const text = buildSkillText(skill);
expect(text).toContain('test-skill');
expect(text).toContain('a test skill');
expect(text).toContain('tag1');
expect(text).toContain('react');
expect(text).toContain('typescript');
expect(text).toContain('lodash');
});
it('should handle skill with minimal fields', () => {
const skill: SkillSummary = {
name: 'minimal-skill',
tags: [],
popularity: 0,
quality: 50,
verified: false,
};
const buildSkillText = (s: SkillSummary): string => {
const parts: string[] = [s.name];
if (s.description) parts.push(s.description);
if (s.tags?.length) parts.push(s.tags.join(' '));
return parts.join(' ').toLowerCase();
};
const text = buildSkillText(skill);
expect(text).toBe('minimal-skill');
});
});
});
describe('EmbeddingService chunking', () => {
it('should split text into chunks', () => {
const chunkText = (
text: string,
config = { maxTokens: 100, overlapPercent: 15, minChunkSize: 10 }
) => {
const lines = text.split('\n');
const chunks: { content: string; startLine: number; endLine: number }[] = [];
const avgCharsPerToken = 4;
const maxCharsPerChunk = config.maxTokens * avgCharsPerToken;
const overlapChars = Math.floor(maxCharsPerChunk * (config.overlapPercent / 100));
let currentChunk: string[] = [];
let currentChars = 0;
let startLine = 0;
for (let i = 0; i < lines.length; i++) {
const line = lines[i];
const lineChars = line.length + 1;
if (currentChars + lineChars > maxCharsPerChunk && currentChunk.length > 0) {
const content = currentChunk.join('\n');
if (content.length >= config.minChunkSize) {
chunks.push({ content, startLine, endLine: i - 1 });
}
const overlapLines: string[] = [];
let overlapCharsCount = 0;
for (let j = currentChunk.length - 1; j >= 0 && overlapCharsCount < overlapChars; j--) {
overlapLines.unshift(currentChunk[j]);
overlapCharsCount += currentChunk[j].length + 1;
}
currentChunk = overlapLines;
currentChars = overlapCharsCount;
startLine = i - overlapLines.length;
}
currentChunk.push(line);
currentChars += lineChars;
}
if (currentChunk.length > 0) {
const content = currentChunk.join('\n');
if (content.length >= config.minChunkSize) {
chunks.push({ content, startLine, endLine: lines.length - 1 });
}
}
return chunks;
};
const longText = Array(50).fill('This is a line of text for testing.').join('\n');
const chunks = chunkText(longText);
expect(chunks.length).toBeGreaterThan(1);
chunks.forEach((chunk) => {
expect(chunk.content.length).toBeLessThanOrEqual(400);
expect(chunk.startLine).toBeGreaterThanOrEqual(0);
expect(chunk.endLine).toBeGreaterThanOrEqual(chunk.startLine);
});
});
it('should not chunk short text', () => {
const chunkText = (
text: string,
config = { maxTokens: 800, overlapPercent: 15, minChunkSize: 100 }
) => {
const lines = text.split('\n');
if (text.length < config.maxTokens * 4) {
if (text.length >= config.minChunkSize) {
return [{ content: text, startLine: 0, endLine: lines.length - 1 }];
}
return [];
}
return [{ content: text, startLine: 0, endLine: lines.length - 1 }];
};
const shortText = 'This is a short text that should not be chunked.';
const chunks = chunkText(shortText, { maxTokens: 800, overlapPercent: 15, minChunkSize: 10 });
expect(chunks.length).toBe(1);
expect(chunks[0].content).toBe(shortText);
});
});
@@ -0,0 +1,100 @@
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { QueryExpander, expandQuerySimple } from '../expansion.js';
describe('QueryExpander', () => {
let expander: QueryExpander;
beforeEach(() => {
expander = new QueryExpander();
});
afterEach(() => {
expander.clearCache();
});
describe('expandQuerySimple (without LLM)', () => {
it('should expand "auth" to authentication-related terms', () => {
const result = expandQuerySimple('auth');
expect(result.original).toBe('auth');
expect(result.variations.length).toBeGreaterThan(0);
expect(result.variations.some((v) => v.includes('authentication'))).toBe(true);
});
it('should expand "api" to related terms', () => {
const result = expandQuerySimple('api');
expect(result.original).toBe('api');
expect(result.variations.some((v) => v.includes('rest') || v.includes('endpoint'))).toBe(true);
});
it('should expand "test" to testing-related terms', () => {
const result = expandQuerySimple('testing');
expect(result.original).toBe('testing');
expect(result.variations.some((v) => v.includes('test') || v.includes('unit'))).toBe(true);
});
it('should handle queries without synonyms', () => {
const result = expandQuerySimple('xyz123unique');
expect(result.original).toBe('xyz123unique');
expect(result.variations).toEqual([]);
expect(result.weights).toEqual([2.0]);
});
it('should give original query weight of 2.0', () => {
const result = expandQuerySimple('auth');
expect(result.weights[0]).toBe(2.0);
for (let i = 1; i < result.weights.length; i++) {
expect(result.weights[i]).toBe(1.0);
}
});
it('should limit variations to 3', () => {
const result = expandQuerySimple('auth');
expect(result.variations.length).toBeLessThanOrEqual(3);
});
});
describe('expand (fallback without LLM)', () => {
it('should return expanded query without LLM initialization', async () => {
const result = await expander.expand('auth');
expect(result.original).toBe('auth');
expect(result.variations.length).toBeGreaterThan(0);
});
it('should cache results', async () => {
const result1 = await expander.expand('auth');
const result2 = await expander.expand('auth');
expect(result1).toEqual(result2);
});
it('should handle case-insensitive caching', async () => {
const result1 = await expander.expand('Auth');
const result2 = await expander.expand('AUTH');
expect(result1.original).toBe('Auth');
expect(result2.original).toBe('AUTH');
});
});
describe('clearCache', () => {
it('should clear the expansion cache', async () => {
await expander.expand('auth');
expander.clearCache();
const result = await expander.expand('auth');
expect(result).toBeDefined();
});
});
describe('isInitialized', () => {
it('should return false when not initialized with LLM', () => {
expect(expander.isInitialized()).toBe(false);
});
});
});
@@ -0,0 +1,244 @@
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import type { SkillSummary, SkillIndex } from '../../recommend/types.js';
const mockSkills: SkillSummary[] = [
{
name: 'react-auth',
description: 'Authentication utilities for React applications',
tags: ['react', 'auth', 'authentication'],
compatibility: {
frameworks: ['react'],
languages: ['typescript', 'javascript'],
libraries: ['next-auth'],
},
popularity: 500,
quality: 80,
verified: true,
},
{
name: 'vue-forms',
description: 'Form validation library for Vue',
tags: ['vue', 'forms', 'validation'],
compatibility: {
frameworks: ['vue'],
languages: ['typescript', 'javascript'],
libraries: [],
},
popularity: 300,
quality: 75,
verified: false,
},
{
name: 'api-testing',
description: 'API testing utilities for REST endpoints',
tags: ['testing', 'api', 'rest'],
compatibility: {
frameworks: [],
languages: ['typescript'],
libraries: ['jest', 'supertest'],
},
popularity: 400,
quality: 85,
verified: true,
},
{
name: 'login-helper',
description: 'Helper functions for login and authentication flows',
tags: ['auth', 'login', 'oauth'],
compatibility: {
frameworks: ['react', 'vue'],
languages: ['typescript'],
libraries: [],
},
popularity: 200,
quality: 70,
verified: false,
},
];
const mockIndex: SkillIndex = {
version: 1,
lastUpdated: new Date().toISOString(),
skills: mockSkills,
sources: [],
};
vi.mock('better-sqlite3', () => {
return {
default: vi.fn().mockImplementation(() => {
throw new Error("Cannot find module 'better-sqlite3'");
}),
};
});
vi.mock('sqlite-vec', () => {
return {
load: vi.fn(),
};
});
vi.mock('node-llama-cpp', () => {
return {
getLlama: vi.fn().mockImplementation(() => {
throw new Error("Cannot find package 'node-llama-cpp'");
}),
};
});
describe('HybridSearchPipeline', () => {
let HybridSearchPipeline: typeof import('../hybrid.js').HybridSearchPipeline;
let createHybridSearchPipeline: typeof import('../hybrid.js').createHybridSearchPipeline;
let pipeline: InstanceType<typeof HybridSearchPipeline>;
beforeEach(async () => {
const module = await import('../hybrid.js');
HybridSearchPipeline = module.HybridSearchPipeline;
createHybridSearchPipeline = module.createHybridSearchPipeline;
pipeline = createHybridSearchPipeline();
});
afterEach(async () => {
if (pipeline) {
await pipeline.dispose();
}
});
describe('initialization', () => {
it('should create a pipeline', () => {
expect(pipeline).toBeInstanceOf(HybridSearchPipeline);
});
it('should not be initialized before calling initialize()', () => {
expect(pipeline.isInitialized()).toBe(false);
});
it('should be initialized after calling initialize()', async () => {
await pipeline.initialize();
expect(pipeline.isInitialized()).toBe(true);
});
it('should load skills index', async () => {
pipeline.loadSkillsIndex(mockIndex);
const stats = pipeline.getStats();
expect(stats.skillCount).toBe(mockSkills.length);
});
});
describe('search (keyword-only fallback)', () => {
beforeEach(async () => {
pipeline.loadSkillsIndex(mockIndex);
await pipeline.initialize();
});
it('should find skills matching query', async () => {
const response = await pipeline.search({ query: 'authentication' });
expect(response.results.length).toBeGreaterThan(0);
expect(response.results.some((r) => r.skill.name === 'react-auth')).toBe(true);
});
it('should find skills by tag', async () => {
const response = await pipeline.search({ query: 'react' });
expect(response.results.length).toBeGreaterThan(0);
expect(response.results.some((r) => r.skill.tags?.includes('react'))).toBe(true);
});
it('should respect limit parameter', async () => {
const response = await pipeline.search({ query: 'auth', limit: 2 });
expect(response.results.length).toBeLessThanOrEqual(2);
});
it('should include timing information', async () => {
const response = await pipeline.search({ query: 'test' });
expect(typeof response.timing.totalMs).toBe('number');
expect(response.timing.totalMs).toBeGreaterThanOrEqual(0);
expect(response.timing.keywordSearchMs).toBeGreaterThanOrEqual(0);
});
it('should include stats', async () => {
const response = await pipeline.search({ query: 'auth' });
expect(response.stats.candidatesFromKeyword).toBeGreaterThan(0);
expect(response.stats.totalMerged).toBeGreaterThan(0);
});
it('should return original query in response', async () => {
const response = await pipeline.search({ query: 'authentication' });
expect(response.query.original).toBe('authentication');
});
});
describe('search with expansion', () => {
beforeEach(async () => {
pipeline.loadSkillsIndex(mockIndex);
await pipeline.initialize();
});
it('should expand query and find more results', async () => {
const response = await pipeline.search({
query: 'auth',
enableExpansion: true,
});
expect(response.results.length).toBeGreaterThan(0);
expect(response.query.expanded).toBeDefined();
});
it('should include expanded terms in response', async () => {
const response = await pipeline.search({
query: 'auth',
enableExpansion: true,
});
if (response.query.expanded) {
expect(response.query.expanded.original).toBe('auth');
expect(response.query.expanded.weights[0]).toBe(2.0);
}
});
});
describe('getStats', () => {
it('should return stats before initialization', () => {
const stats = pipeline.getStats();
expect(stats.initialized).toBe(false);
expect(stats.skillCount).toBe(0);
});
it('should return updated stats after loading index', async () => {
pipeline.loadSkillsIndex(mockIndex);
await pipeline.initialize();
const stats = pipeline.getStats();
expect(stats.initialized).toBe(true);
expect(stats.skillCount).toBe(mockSkills.length);
});
});
});
describe('hybridSearch helper', () => {
let hybridSearch: typeof import('../hybrid.js').hybridSearch;
beforeEach(async () => {
const module = await import('../hybrid.js');
hybridSearch = module.hybridSearch;
});
it('should perform search on skills array', async () => {
const response = await hybridSearch(mockSkills, 'react');
expect(response.results.length).toBeGreaterThan(0);
expect(response.query.original).toBe('react');
});
it('should respect options', async () => {
const response = await hybridSearch(mockSkills, 'auth', {
limit: 1,
});
expect(response.results.length).toBe(1);
});
});
@@ -0,0 +1,276 @@
import { describe, it, expect } from 'vitest';
import {
computeRRFScore,
fuseWithRRF,
normalizeScores,
weightedCombine,
applyPositionAwareBlending,
getRankFromScore,
mergeRankings,
type RankerResult,
type RRFInput,
} from '../rrf.js';
describe('RRF (Reciprocal Rank Fusion)', () => {
describe('computeRRFScore', () => {
it('should compute RRF score for a single rank', () => {
const score = computeRRFScore([1], 60);
expect(score).toBeCloseTo(1 / 61, 5);
});
it('should sum RRF scores for multiple ranks', () => {
const score = computeRRFScore([1, 2, 3], 60);
const expected = 1 / 61 + 1 / 62 + 1 / 63;
expect(score).toBeCloseTo(expected, 5);
});
it('should use custom k value', () => {
const scoreK60 = computeRRFScore([1], 60);
const scoreK30 = computeRRFScore([1], 30);
expect(scoreK30).toBeGreaterThan(scoreK60);
});
it('should return 0 for empty ranks', () => {
const score = computeRRFScore([]);
expect(score).toBe(0);
});
});
describe('fuseWithRRF', () => {
it('should fuse results from multiple rankers', () => {
const inputs: RRFInput[] = [
{
source: 'vector',
results: [
{ skillName: 'skill-a', score: 0.9 },
{ skillName: 'skill-b', score: 0.8 },
{ skillName: 'skill-c', score: 0.7 },
],
},
{
source: 'keyword',
results: [
{ skillName: 'skill-b', score: 90 },
{ skillName: 'skill-a', score: 80 },
{ skillName: 'skill-d', score: 70 },
],
},
];
const rankings = fuseWithRRF(inputs, 60);
expect(rankings.length).toBe(4);
expect(rankings[0].skillName).toBe('skill-a');
expect(rankings[1].skillName).toBe('skill-b');
});
it('should include rank information from each source', () => {
const inputs: RRFInput[] = [
{
source: 'vector',
results: [{ skillName: 'skill-a', score: 0.9 }],
},
{
source: 'keyword',
results: [{ skillName: 'skill-a', score: 90 }],
},
];
const rankings = fuseWithRRF(inputs);
expect(rankings[0].ranks).toHaveLength(2);
expect(rankings[0].ranks.map((r) => r.source)).toContain('vector');
expect(rankings[0].ranks.map((r) => r.source)).toContain('keyword');
});
it('should handle skills appearing in only one ranker', () => {
const inputs: RRFInput[] = [
{
source: 'vector',
results: [{ skillName: 'skill-a', score: 0.9 }],
},
{
source: 'keyword',
results: [{ skillName: 'skill-b', score: 90 }],
},
];
const rankings = fuseWithRRF(inputs);
expect(rankings).toHaveLength(2);
const skillAInfo = rankings.find((r) => r.skillName === 'skill-a');
const skillBInfo = rankings.find((r) => r.skillName === 'skill-b');
expect(skillAInfo?.ranks).toHaveLength(1);
expect(skillBInfo?.ranks).toHaveLength(1);
});
});
describe('normalizeScores', () => {
it('should normalize scores to 0-1 range', () => {
const results: RankerResult[] = [
{ skillName: 'a', score: 100 },
{ skillName: 'b', score: 50 },
{ skillName: 'c', score: 0 },
];
const normalized = normalizeScores(results);
expect(normalized[0].score).toBe(1);
expect(normalized[1].score).toBe(0.5);
expect(normalized[2].score).toBe(0);
});
it('should handle all same scores', () => {
const results: RankerResult[] = [
{ skillName: 'a', score: 50 },
{ skillName: 'b', score: 50 },
];
const normalized = normalizeScores(results);
expect(normalized[0].score).toBe(1);
expect(normalized[1].score).toBe(1);
});
it('should return empty array for empty input', () => {
const normalized = normalizeScores([]);
expect(normalized).toEqual([]);
});
});
describe('weightedCombine', () => {
it('should combine results with weights', () => {
const inputs: RRFInput[] = [
{
source: 'vector',
results: [
{ skillName: 'a', score: 100 },
{ skillName: 'b', score: 50 },
],
},
{
source: 'keyword',
results: [
{ skillName: 'b', score: 100 },
{ skillName: 'a', score: 50 },
],
},
];
const combined = weightedCombine(inputs, { vector: 0.6, keyword: 0.4 });
expect(combined).toHaveLength(2);
const skillA = combined.find((r) => r.skillName === 'a')!;
const skillB = combined.find((r) => r.skillName === 'b')!;
expect(skillA.score).toBeCloseTo(0.6 * 1 + 0.4 * 0, 5);
expect(skillB.score).toBeCloseTo(0.6 * 0 + 0.4 * 1, 5);
});
it('should default to weight 1 for unknown sources', () => {
const inputs: RRFInput[] = [
{
source: 'unknown',
results: [{ skillName: 'a', score: 100 }],
},
];
const combined = weightedCombine(inputs, {});
expect(combined[0].score).toBe(1);
});
});
describe('applyPositionAwareBlending', () => {
it('should apply different weights based on position', () => {
const retrievalScores = new Map([
['a', 0.9],
['b', 0.8],
['c', 0.7],
['d', 0.6],
]);
const rerankerScores = new Map([
['a', 0.5],
['b', 0.6],
['c', 0.7],
['d', 0.8],
]);
const sortedSkills = ['a', 'b', 'c', 'd'];
const blended = applyPositionAwareBlending(
retrievalScores,
rerankerScores,
sortedSkills
);
const scoreA = blended.get('a')!;
expect(scoreA).toBeCloseTo(0.9 * 0.75 + 0.5 * 0.25, 5);
const scoreD = blended.get('d')!;
expect(scoreD).toBeCloseTo(0.6 * 0.6 + 0.8 * 0.4, 5);
});
it('should handle missing scores', () => {
const retrievalScores = new Map([['a', 0.9]]);
const rerankerScores = new Map<string, number>();
const sortedSkills = ['a'];
const blended = applyPositionAwareBlending(
retrievalScores,
rerankerScores,
sortedSkills
);
expect(blended.get('a')).toBeCloseTo(0.9 * 0.75, 5);
});
});
describe('getRankFromScore', () => {
it('should return correct rank for a skill', () => {
const results: RankerResult[] = [
{ skillName: 'a', score: 90 },
{ skillName: 'b', score: 80 },
{ skillName: 'c', score: 70 },
];
expect(getRankFromScore('a', results)).toBe(1);
expect(getRankFromScore('b', results)).toBe(2);
expect(getRankFromScore('c', results)).toBe(3);
});
it('should return length+1 for missing skill', () => {
const results: RankerResult[] = [
{ skillName: 'a', score: 90 },
{ skillName: 'b', score: 80 },
];
expect(getRankFromScore('missing', results)).toBe(3);
});
});
describe('mergeRankings', () => {
it('should merge primary and secondary rankings with weights', () => {
const primary = [
{ skillName: 'a', rrfScore: 0.1, ranks: [{ source: 'primary', rank: 1 }] },
{ skillName: 'b', rrfScore: 0.05, ranks: [{ source: 'primary', rank: 2 }] },
];
const secondary = [
{ skillName: 'b', rrfScore: 0.1, ranks: [{ source: 'secondary', rank: 1 }] },
{ skillName: 'c', rrfScore: 0.05, ranks: [{ source: 'secondary', rank: 2 }] },
];
const merged = mergeRankings(primary, secondary, 0.7);
expect(merged).toHaveLength(3);
const skillA = merged.find((r) => r.skillName === 'a')!;
const skillB = merged.find((r) => r.skillName === 'b')!;
const skillC = merged.find((r) => r.skillName === 'c')!;
expect(skillA.rrfScore).toBeCloseTo(0.1 * 0.7, 5);
expect(skillB.rrfScore).toBeCloseTo(0.05 * 0.7 + 0.1 * 0.3, 5);
expect(skillC.rrfScore).toBeCloseTo(0.05 * 0.3, 5);
});
});
});
+294
View File
@@ -0,0 +1,294 @@
import type { SkillSummary } from '../recommend/types.js';
import type {
SkillEmbedding,
IndexBuildCallback,
} from './types.js';
import { DEFAULT_CHUNKING_CONFIG, MODEL_REGISTRY } from './types.js';
import { LocalModelManager } from './local-models.js';
export class EmbeddingService {
private modelManager: LocalModelManager;
private model: unknown = null;
private context: unknown = null;
private initialized = false;
private dimensions: number = 768;
constructor(modelManager?: LocalModelManager) {
this.modelManager = modelManager ?? new LocalModelManager();
}
async initialize(onProgress?: IndexBuildCallback): Promise<void> {
if (this.initialized) return;
onProgress?.({
phase: 'loading',
current: 0,
total: 1,
message: 'Loading embedding model...',
});
const modelPath = await this.modelManager.ensureEmbedModel(onProgress);
try {
// @ts-ignore - node-llama-cpp is an optional dependency
const llama = await import('node-llama-cpp');
const { getLlama } = llama;
const llamaInstance = await getLlama();
this.model = await llamaInstance.loadModel({ modelPath });
this.context = await (this.model as { createEmbeddingContext: () => Promise<unknown> }).createEmbeddingContext();
const modelInfo = MODEL_REGISTRY.embeddings[
this.modelManager.getConfig().embedModel as keyof typeof MODEL_REGISTRY.embeddings
];
this.dimensions = modelInfo?.dimensions ?? 768;
this.initialized = true;
onProgress?.({
phase: 'loading',
current: 1,
total: 1,
message: 'Embedding model loaded successfully',
});
} catch (error) {
if (
error instanceof Error &&
error.message.includes("Cannot find package 'node-llama-cpp'")
) {
throw new Error(
'node-llama-cpp is not installed. Install it with: pnpm add node-llama-cpp'
);
}
throw error;
}
}
async embed(text: string): Promise<Float32Array> {
if (!this.initialized || !this.context) {
throw new Error('EmbeddingService not initialized. Call initialize() first.');
}
const ctx = this.context as {
getEmbeddingFor(text: string): Promise<{ vector: number[] }>;
};
const result = await ctx.getEmbeddingFor(text);
return new Float32Array(result.vector);
}
async embedBatch(texts: string[]): Promise<Float32Array[]> {
const results: Float32Array[] = [];
for (const text of texts) {
results.push(await this.embed(text));
}
return results;
}
async embedSkill(skill: SkillSummary): Promise<SkillEmbedding> {
const textContent = this.buildSkillText(skill);
const vector = await this.embed(textContent);
return {
skillName: skill.name,
vector,
textContent,
generatedAt: new Date().toISOString(),
};
}
async embedSkillWithChunks(
skill: SkillSummary,
fullContent?: string
): Promise<SkillEmbedding> {
const textContent = this.buildSkillText(skill);
const mainVector = await this.embed(textContent);
const chunks = fullContent ? this.chunkText(fullContent) : undefined;
let embeddedChunks: SkillEmbedding['chunks'] | undefined;
if (chunks && chunks.length > 0) {
embeddedChunks = [];
for (const chunk of chunks) {
const chunkVector = await this.embed(chunk.content);
embeddedChunks.push({
content: chunk.content,
vector: chunkVector,
startLine: chunk.startLine,
endLine: chunk.endLine,
});
}
}
return {
skillName: skill.name,
vector: mainVector,
textContent,
chunks: embeddedChunks,
generatedAt: new Date().toISOString(),
};
}
async embedSkills(
skills: SkillSummary[],
onProgress?: IndexBuildCallback
): Promise<SkillEmbedding[]> {
await this.initialize(onProgress);
const embeddings: SkillEmbedding[] = [];
const total = skills.length;
for (let i = 0; i < skills.length; i++) {
const skill = skills[i];
onProgress?.({
phase: 'embedding',
current: i + 1,
total,
skillName: skill.name,
message: `Embedding skill ${i + 1}/${total}: ${skill.name}`,
});
const embedding = await this.embedSkill(skill);
embeddings.push(embedding);
}
onProgress?.({
phase: 'complete',
current: total,
total,
message: `Embedded ${total} skills`,
});
return embeddings;
}
private buildSkillText(skill: SkillSummary): string {
const parts: string[] = [skill.name];
if (skill.description) {
parts.push(skill.description);
}
if (skill.tags && skill.tags.length > 0) {
parts.push(skill.tags.join(' '));
}
if (skill.compatibility) {
if (skill.compatibility.frameworks?.length) {
parts.push(skill.compatibility.frameworks.join(' '));
}
if (skill.compatibility.languages?.length) {
parts.push(skill.compatibility.languages.join(' '));
}
if (skill.compatibility.libraries?.length) {
parts.push(skill.compatibility.libraries.join(' '));
}
}
return parts.join(' ').toLowerCase();
}
private chunkText(
text: string,
config = DEFAULT_CHUNKING_CONFIG
): { content: string; startLine: number; endLine: number }[] {
const lines = text.split('\n');
const chunks: { content: string; startLine: number; endLine: number }[] = [];
const avgCharsPerToken = 4;
const maxCharsPerChunk = config.maxTokens * avgCharsPerToken;
const overlapChars = Math.floor(maxCharsPerChunk * (config.overlapPercent / 100));
let currentChunk: string[] = [];
let currentChars = 0;
let startLine = 0;
for (let i = 0; i < lines.length; i++) {
const line = lines[i];
const lineChars = line.length + 1;
if (currentChars + lineChars > maxCharsPerChunk && currentChunk.length > 0) {
const content = currentChunk.join('\n');
if (content.length >= config.minChunkSize) {
chunks.push({
content,
startLine,
endLine: i - 1,
});
}
const overlapLines: string[] = [];
let overlapCharsCount = 0;
for (let j = currentChunk.length - 1; j >= 0 && overlapCharsCount < overlapChars; j--) {
overlapLines.unshift(currentChunk[j]);
overlapCharsCount += currentChunk[j].length + 1;
}
currentChunk = overlapLines;
currentChars = overlapCharsCount;
startLine = Math.max(0, i - overlapLines.length);
}
currentChunk.push(line);
currentChars += lineChars;
}
if (currentChunk.length > 0) {
const content = currentChunk.join('\n');
if (content.length >= config.minChunkSize) {
chunks.push({
content,
startLine,
endLine: lines.length - 1,
});
}
}
return chunks;
}
cosineSimilarity(a: Float32Array, b: Float32Array): number {
if (a.length !== b.length) {
throw new Error(`Vector dimensions mismatch: ${a.length} vs ${b.length}`);
}
let dotProduct = 0;
let normA = 0;
let normB = 0;
for (let i = 0; i < a.length; i++) {
dotProduct += a[i] * b[i];
normA += a[i] * a[i];
normB += b[i] * b[i];
}
const magnitude = Math.sqrt(normA) * Math.sqrt(normB);
if (magnitude === 0) return 0;
return dotProduct / magnitude;
}
getDimensions(): number {
return this.dimensions;
}
isInitialized(): boolean {
return this.initialized;
}
async dispose(): Promise<void> {
if (this.context && typeof (this.context as { dispose?: () => void }).dispose === 'function') {
(this.context as { dispose: () => void }).dispose();
}
if (this.model && typeof (this.model as { dispose?: () => void }).dispose === 'function') {
(this.model as { dispose: () => void }).dispose();
}
this.context = null;
this.model = null;
this.initialized = false;
}
}
export function createEmbeddingService(modelManager?: LocalModelManager): EmbeddingService {
return new EmbeddingService(modelManager);
}
+236
View File
@@ -0,0 +1,236 @@
import type { ExpandedQuery, IndexBuildCallback } from './types.js';
import { DEFAULT_HYBRID_CONFIG } from './types.js';
import { LocalModelManager } from './local-models.js';
interface CacheEntry {
query: ExpandedQuery;
timestamp: number;
}
const expansionCache = new Map<string, CacheEntry>();
export class QueryExpander {
private modelManager: LocalModelManager;
private model: unknown = null;
private context: unknown = null;
private initialized = false;
private cacheTtlMs: number;
constructor(modelManager?: LocalModelManager, cacheTtlMs?: number) {
this.modelManager = modelManager ?? new LocalModelManager();
this.cacheTtlMs = cacheTtlMs ?? DEFAULT_HYBRID_CONFIG.expansionCacheTtlMs;
}
async initialize(onProgress?: IndexBuildCallback): Promise<void> {
if (this.initialized) return;
onProgress?.({
phase: 'loading',
current: 0,
total: 1,
message: 'Loading LLM model for query expansion...',
});
const modelPath = await this.modelManager.ensureLlmModel(onProgress);
try {
// @ts-ignore - node-llama-cpp is an optional dependency
const llamaModule = await import('node-llama-cpp');
const { getLlama, LlamaChatSession } = llamaModule;
const llama = await getLlama();
this.model = await llama.loadModel({ modelPath });
const ctx = await (this.model as { createContext: (opts?: { contextSize?: number }) => Promise<{ getSequence: () => unknown }> }).createContext({ contextSize: 2048 });
this.context = new LlamaChatSession({ contextSequence: ctx.getSequence() as never });
this.initialized = true;
onProgress?.({
phase: 'loading',
current: 1,
total: 1,
message: 'LLM model loaded successfully',
});
} catch (error) {
if (
error instanceof Error &&
error.message.includes("Cannot find package 'node-llama-cpp'")
) {
throw new Error(
'node-llama-cpp is not installed. Install it with: pnpm add node-llama-cpp'
);
}
throw error;
}
}
async expand(query: string, maxVariations: number = 3): Promise<ExpandedQuery> {
const cached = this.getFromCache(query);
if (cached) {
return cached;
}
if (!this.initialized) {
return this.expandWithoutLLM(query);
}
try {
const variations = await this.generateVariations(query, maxVariations);
const weights = [2.0, ...variations.map(() => 1.0)];
const expanded: ExpandedQuery = {
original: query,
variations,
weights,
};
this.addToCache(query, expanded);
return expanded;
} catch {
return this.expandWithoutLLM(query);
}
}
private async generateVariations(query: string, maxVariations: number): Promise<string[]> {
const session = this.context as {
prompt(text: string): Promise<string>;
};
const prompt = `Generate ${maxVariations} alternative search queries for finding software development skills related to: "${query}"
Rules:
- Each alternative should use different terminology but capture the same intent
- Keep each alternative concise (2-5 words)
- Focus on technical terms and synonyms
- Output only the alternatives, one per line, no numbering
Example:
Query: "auth for react"
Alternatives:
authentication react
login react hooks
OAuth react integration
Query: "${query}"
Alternatives:`;
const response = await session.prompt(prompt);
const variations = response
.split('\n')
.map((line) => line.trim())
.filter((line) => line.length > 0 && line.length < 100)
.filter((line) => !line.startsWith('-') && !line.match(/^\d+\./))
.slice(0, maxVariations);
return variations;
}
private expandWithoutLLM(query: string): ExpandedQuery {
const variations: string[] = [];
const queryLower = query.toLowerCase();
const synonyms: Record<string, string[]> = {
auth: ['authentication', 'login', 'oauth', 'jwt'],
authentication: ['auth', 'login', 'oauth'],
login: ['auth', 'authentication', 'signin'],
api: ['rest', 'endpoint', 'http', 'graphql'],
rest: ['api', 'http', 'endpoint'],
db: ['database', 'sql', 'storage'],
database: ['db', 'sql', 'data storage'],
test: ['testing', 'unit test', 'spec'],
testing: ['test', 'unit test', 'e2e'],
ui: ['user interface', 'frontend', 'component'],
frontend: ['ui', 'client', 'browser'],
backend: ['server', 'api', 'service'],
form: ['input', 'validation', 'submit'],
validation: ['form validation', 'input check', 'verify'],
state: ['state management', 'store', 'data flow'],
animation: ['motion', 'transition', 'animate'],
style: ['styling', 'css', 'design'],
css: ['style', 'styling', 'tailwind'],
};
const terms = queryLower.split(/\s+/);
for (const term of terms) {
const termSynonyms = synonyms[term];
if (termSynonyms) {
for (const syn of termSynonyms.slice(0, 2)) {
const variation = query.replace(new RegExp(term, 'i'), syn);
if (variation !== query && !variations.includes(variation)) {
variations.push(variation);
}
}
}
}
const limitedVariations = variations.slice(0, 3);
const weights = [2.0, ...limitedVariations.map(() => 1.0)];
return {
original: query,
variations: limitedVariations,
weights,
};
}
private getFromCache(query: string): ExpandedQuery | null {
const entry = expansionCache.get(query.toLowerCase());
if (!entry) return null;
const now = Date.now();
if (now - entry.timestamp > this.cacheTtlMs) {
expansionCache.delete(query.toLowerCase());
return null;
}
return entry.query;
}
private addToCache(query: string, expanded: ExpandedQuery): void {
const maxCacheSize = 100;
if (expansionCache.size >= maxCacheSize) {
const oldestKey = expansionCache.keys().next().value;
if (oldestKey) {
expansionCache.delete(oldestKey);
}
}
expansionCache.set(query.toLowerCase(), {
query: expanded,
timestamp: Date.now(),
});
}
clearCache(): void {
expansionCache.clear();
}
isInitialized(): boolean {
return this.initialized;
}
async dispose(): Promise<void> {
if (this.context && typeof (this.context as { dispose?: () => void }).dispose === 'function') {
(this.context as { dispose: () => void }).dispose();
}
if (this.model && typeof (this.model as { dispose?: () => void }).dispose === 'function') {
(this.model as { dispose: () => void }).dispose();
}
this.context = null;
this.model = null;
this.initialized = false;
}
}
export function createQueryExpander(
modelManager?: LocalModelManager,
cacheTtlMs?: number
): QueryExpander {
return new QueryExpander(modelManager, cacheTtlMs);
}
export function expandQuerySimple(query: string): ExpandedQuery {
const expander = new QueryExpander();
return expander['expandWithoutLLM'](query);
}
+384
View File
@@ -0,0 +1,384 @@
import type { SkillSummary, SkillIndex } from '../recommend/types.js';
import type {
HybridSearchOptions,
HybridSearchResult,
HybridSearchResponse,
ExpandedQuery,
IndexBuildCallback,
RerankerInput,
RerankerOutput,
LocalModelConfig,
} from './types.js';
import { DEFAULT_HYBRID_CONFIG } from './types.js';
import { EmbeddingService, createEmbeddingService } from './embeddings.js';
import { VectorStore, createVectorStore } from './vector-store.js';
import { QueryExpander, createQueryExpander } from './expansion.js';
import { LocalModelManager } from './local-models.js';
import {
fuseWithRRF,
applyPositionAwareBlending,
type RankerResult,
type RRFInput,
} from './rrf.js';
import { RecommendationEngine } from '../recommend/engine.js';
export class HybridSearchPipeline {
private embeddingService: EmbeddingService;
private vectorStore: VectorStore;
private queryExpander: QueryExpander;
private modelManager: LocalModelManager;
private recommendationEngine: RecommendationEngine;
private initialized = false;
private skillsMap: Map<string, SkillSummary> = new Map();
constructor(config: Partial<LocalModelConfig> = {}) {
this.modelManager = new LocalModelManager(config);
this.embeddingService = createEmbeddingService(this.modelManager);
this.vectorStore = createVectorStore(undefined, this.embeddingService);
this.queryExpander = createQueryExpander(this.modelManager);
this.recommendationEngine = new RecommendationEngine();
}
async initialize(onProgress?: IndexBuildCallback): Promise<void> {
if (this.initialized) return;
await this.vectorStore.initialize();
this.initialized = true;
onProgress?.({
phase: 'complete',
current: 1,
total: 1,
message: 'Hybrid search pipeline initialized',
});
}
async buildIndex(
skills: SkillSummary[],
onProgress?: IndexBuildCallback
): Promise<void> {
await this.initialize(onProgress);
this.skillsMap.clear();
for (const skill of skills) {
this.skillsMap.set(skill.name, skill);
}
const index: SkillIndex = {
version: 1,
lastUpdated: new Date().toISOString(),
skills,
sources: [],
};
this.recommendationEngine.loadIndex(index);
try {
await this.embeddingService.initialize(onProgress);
const embeddings = await this.embeddingService.embedSkills(skills, onProgress);
await this.vectorStore.storeBatch(embeddings, onProgress);
onProgress?.({
phase: 'complete',
current: skills.length,
total: skills.length,
message: `Indexed ${skills.length} skills with embeddings`,
});
} catch {
// Embeddings not available - will use keyword-only search
onProgress?.({
phase: 'complete',
current: skills.length,
total: skills.length,
message: `Indexed ${skills.length} skills (keyword-only, embeddings unavailable)`,
});
}
}
async search(options: HybridSearchOptions): Promise<HybridSearchResponse> {
const startTime = Date.now();
const timing: HybridSearchResponse['timing'] = { totalMs: 0 };
const stats: HybridSearchResponse['stats'] = {
candidatesFromVector: 0,
candidatesFromKeyword: 0,
totalMerged: 0,
reranked: 0,
};
await this.initialize();
const {
query,
limit = 10,
enableExpansion = false,
enableReranking = false,
rrfK = DEFAULT_HYBRID_CONFIG.rrfK,
positionAwareBlending = true,
} = options;
let expandedQuery: ExpandedQuery | undefined;
const searchQueries: string[] = [query];
if (enableExpansion) {
try {
expandedQuery = await this.queryExpander.expand(query);
searchQueries.push(...expandedQuery.variations);
} catch {
expandedQuery = {
original: query,
variations: [],
weights: [2.0],
};
}
}
const rankerInputs: RRFInput[] = [];
const embeddingStart = Date.now();
let queryVector: Float32Array | null = null;
try {
if (this.embeddingService.isInitialized()) {
queryVector = await this.embeddingService.embed(query);
}
} catch {
}
timing.embeddingMs = Date.now() - embeddingStart;
if (queryVector) {
const vectorStart = Date.now();
const vectorResults = await this.vectorStore.search(queryVector, limit * 3);
timing.vectorSearchMs = Date.now() - vectorStart;
const vectorRankerResults: RankerResult[] = vectorResults.map((r) => ({
skillName: r.skillName,
score: r.similarity,
}));
rankerInputs.push({
source: 'vector',
results: vectorRankerResults,
});
stats.candidatesFromVector = vectorResults.length;
}
const keywordStart = Date.now();
const keywordResults: RankerResult[] = [];
for (let i = 0; i < searchQueries.length; i++) {
const searchQuery = searchQueries[i];
const weight = expandedQuery?.weights[i] ?? 1;
const results = this.recommendationEngine.search({
query: searchQuery,
limit: limit * 3,
semantic: true,
});
for (const result of results) {
const existing = keywordResults.find(
(r) => r.skillName === result.skill.name
);
if (existing) {
existing.score = Math.max(existing.score, result.relevance * weight);
} else {
keywordResults.push({
skillName: result.skill.name,
score: result.relevance * weight,
});
}
}
}
timing.keywordSearchMs = Date.now() - keywordStart;
rankerInputs.push({
source: 'keyword',
results: keywordResults,
});
stats.candidatesFromKeyword = keywordResults.length;
const fusionStart = Date.now();
const rrfRankings = fuseWithRRF(rankerInputs, rrfK);
timing.fusionMs = Date.now() - fusionStart;
stats.totalMerged = rrfRankings.length;
let finalScores = new Map<string, number>();
for (const ranking of rrfRankings) {
finalScores.set(ranking.skillName, ranking.rrfScore);
}
if (enableReranking && rrfRankings.length > 0) {
const rerankStart = Date.now();
const topCandidates = rrfRankings.slice(0, DEFAULT_HYBRID_CONFIG.rerankTopN);
const rerankerInputs: RerankerInput[] = topCandidates
.map((r) => {
const skill = this.skillsMap.get(r.skillName);
if (!skill) return null;
return {
query,
skillName: r.skillName,
skillDescription: skill.description ?? '',
skillTags: skill.tags ?? [],
};
})
.filter((r): r is RerankerInput => r !== null);
const rerankerOutputs = await this.rerank(rerankerInputs);
timing.rerankingMs = Date.now() - rerankStart;
stats.reranked = rerankerOutputs.length;
if (positionAwareBlending && rerankerOutputs.length > 0) {
const retrievalScores = new Map<string, number>();
const maxRrfScore = Math.max(...rrfRankings.map((r) => r.rrfScore));
for (const ranking of topCandidates) {
retrievalScores.set(
ranking.skillName,
ranking.rrfScore / (maxRrfScore || 1)
);
}
const rerankerScores = new Map<string, number>();
const maxRerankerScore = Math.max(...rerankerOutputs.map((r) => r.score));
for (const output of rerankerOutputs) {
rerankerScores.set(
output.skillName,
output.score / (maxRerankerScore || 1)
);
}
const sortedSkillNames = topCandidates.map((r) => r.skillName);
const blendedScores = applyPositionAwareBlending(
retrievalScores,
rerankerScores,
sortedSkillNames
);
for (const [skillName, score] of blendedScores) {
finalScores.set(skillName, score);
}
}
}
const sortedResults = Array.from(finalScores.entries())
.sort((a, b) => b[1] - a[1])
.slice(0, limit);
const vectorInput = rankerInputs.find((r) => r.source === 'vector');
const keywordInput = rankerInputs.find((r) => r.source === 'keyword');
const hybridResults: HybridSearchResult[] = [];
for (const [skillName, hybridScore] of sortedResults) {
const skill = this.skillsMap.get(skillName);
if (!skill) continue;
hybridResults.push({
skill,
relevance: Math.round(hybridScore * 100),
hybridScore,
vectorSimilarity: vectorInput?.results.find((r) => r.skillName === skillName)?.score,
keywordScore: keywordInput?.results.find((r) => r.skillName === skillName)?.score,
rrfScore: rrfRankings.find((r) => r.skillName === skillName)?.rrfScore,
matchedTerms: [],
expandedTerms: expandedQuery?.variations,
});
}
timing.totalMs = Date.now() - startTime;
return {
results: hybridResults,
query: {
original: query,
expanded: expandedQuery,
},
timing,
stats,
};
}
private async rerank(inputs: RerankerInput[]): Promise<RerankerOutput[]> {
const outputs: RerankerOutput[] = [];
for (const input of inputs) {
const baseScore =
(input.skillDescription.toLowerCase().includes(input.query.toLowerCase())
? 0.5
: 0) +
(input.skillTags.some((t) =>
t.toLowerCase().includes(input.query.toLowerCase())
)
? 0.3
: 0) +
(input.skillName.toLowerCase().includes(input.query.toLowerCase())
? 0.2
: 0);
outputs.push({
skillName: input.skillName,
score: Math.min(1, baseScore + 0.3),
});
}
return outputs;
}
loadSkillsIndex(index: SkillIndex): void {
this.skillsMap.clear();
for (const skill of index.skills) {
this.skillsMap.set(skill.name, skill);
}
this.recommendationEngine.loadIndex(index);
}
getStats(): {
vectorStore: ReturnType<VectorStore['getStats']>;
initialized: boolean;
skillCount: number;
} {
return {
vectorStore: this.vectorStore.getStats(),
initialized: this.initialized,
skillCount: this.skillsMap.size,
};
}
isInitialized(): boolean {
return this.initialized;
}
async dispose(): Promise<void> {
await this.embeddingService.dispose();
await this.queryExpander.dispose();
await this.vectorStore.close();
this.initialized = false;
}
}
export function createHybridSearchPipeline(
config?: Partial<LocalModelConfig>
): HybridSearchPipeline {
return new HybridSearchPipeline(config);
}
export async function hybridSearch(
skills: SkillSummary[],
query: string,
options: Partial<HybridSearchOptions> = {}
): Promise<HybridSearchResponse> {
const pipeline = createHybridSearchPipeline();
try {
await pipeline.buildIndex(skills);
return await pipeline.search({
query,
...options,
});
} finally {
await pipeline.dispose();
}
}
+7
View File
@@ -0,0 +1,7 @@
export * from './types.js';
export * from './local-models.js';
export * from './embeddings.js';
export * from './vector-store.js';
export * from './rrf.js';
export * from './expansion.js';
export * from './hybrid.js';
+243
View File
@@ -0,0 +1,243 @@
import * as fs from 'node:fs';
import * as path from 'node:path';
import * as os from 'node:os';
import { createWriteStream } from 'node:fs';
import type { LocalModelConfig, IndexBuildCallback } from './types.js';
import { MODEL_REGISTRY } from './types.js';
const DEFAULT_MODEL_DIR = path.join(os.homedir(), '.skillkit', 'models');
type EmbeddingModelName = keyof typeof MODEL_REGISTRY.embeddings;
type LlmModelName = keyof typeof MODEL_REGISTRY.llm;
interface ModelInfo {
url: string;
size: number;
description: string;
dimensions?: number;
}
export class LocalModelManager {
private config: Required<LocalModelConfig>;
private embedModelPath: string | null = null;
private llmModelPath: string | null = null;
constructor(config: Partial<LocalModelConfig> = {}) {
this.config = {
embedModel: config.embedModel ?? 'nomic-embed-text-v1.5.Q4_K_M.gguf',
llmModel: config.llmModel ?? 'gemma-2b-it-Q4_K_M.gguf',
modelDir: config.modelDir ?? DEFAULT_MODEL_DIR,
autoDownload: config.autoDownload ?? true,
gpuLayers: config.gpuLayers ?? 0,
};
}
async ensureModelsDirectory(): Promise<void> {
if (!fs.existsSync(this.config.modelDir)) {
await fs.promises.mkdir(this.config.modelDir, { recursive: true });
}
}
getEmbedModelPath(): string {
return path.join(this.config.modelDir, this.config.embedModel);
}
getLlmModelPath(): string {
return path.join(this.config.modelDir, this.config.llmModel);
}
isEmbedModelAvailable(): boolean {
return fs.existsSync(this.getEmbedModelPath());
}
isLlmModelAvailable(): boolean {
return fs.existsSync(this.getLlmModelPath());
}
private getModelInfo(modelType: 'embed' | 'llm', modelName: string): ModelInfo | undefined {
if (modelType === 'embed') {
return MODEL_REGISTRY.embeddings[modelName as EmbeddingModelName] as ModelInfo | undefined;
}
return MODEL_REGISTRY.llm[modelName as LlmModelName] as ModelInfo | undefined;
}
async downloadModel(
modelType: 'embed' | 'llm',
onProgress?: IndexBuildCallback
): Promise<string> {
await this.ensureModelsDirectory();
const modelName = modelType === 'embed' ? this.config.embedModel : this.config.llmModel;
const modelPath = modelType === 'embed' ? this.getEmbedModelPath() : this.getLlmModelPath();
if (fs.existsSync(modelPath)) {
return modelPath;
}
const modelInfo = this.getModelInfo(modelType, modelName);
if (!modelInfo) {
const availableModels = modelType === 'embed'
? Object.keys(MODEL_REGISTRY.embeddings)
: Object.keys(MODEL_REGISTRY.llm);
throw new Error(`Unknown model: ${modelName}. Available models: ${availableModels.join(', ')}`);
}
onProgress?.({
phase: 'downloading',
current: 0,
total: modelInfo.size,
message: `Downloading ${modelName}...`,
});
const response = await fetch(modelInfo.url);
if (!response.ok) {
throw new Error(`Failed to download model: ${response.statusText}`);
}
const contentLength = Number(response.headers.get('content-length')) || modelInfo.size;
let downloaded = 0;
const tempPath = `${modelPath}.tmp`;
const fileStream = createWriteStream(tempPath);
const reader = response.body?.getReader();
if (!reader) {
throw new Error('Failed to get response body reader');
}
try {
while (true) {
const { done, value } = await reader.read();
if (done) break;
const canContinue = fileStream.write(Buffer.from(value));
if (!canContinue) {
await new Promise<void>((resolve) => fileStream.once('drain', resolve));
}
downloaded += value.length;
onProgress?.({
phase: 'downloading',
current: downloaded,
total: contentLength,
message: `Downloading ${modelName}: ${Math.round((downloaded / contentLength) * 100)}%`,
});
}
fileStream.end();
await new Promise<void>((resolve, reject) => {
fileStream.on('finish', resolve);
fileStream.on('error', reject);
});
await fs.promises.rename(tempPath, modelPath);
return modelPath;
} catch (error) {
if (fs.existsSync(tempPath)) {
await fs.promises.unlink(tempPath);
}
throw error;
}
}
async ensureEmbedModel(onProgress?: IndexBuildCallback): Promise<string> {
if (this.embedModelPath && fs.existsSync(this.embedModelPath)) {
return this.embedModelPath;
}
if (!this.isEmbedModelAvailable()) {
if (!this.config.autoDownload) {
throw new Error(
`Embedding model not found at ${this.getEmbedModelPath()}. ` +
'Set autoDownload: true or manually download the model.'
);
}
this.embedModelPath = await this.downloadModel('embed', onProgress);
} else {
this.embedModelPath = this.getEmbedModelPath();
}
return this.embedModelPath;
}
async ensureLlmModel(onProgress?: IndexBuildCallback): Promise<string> {
if (this.llmModelPath && fs.existsSync(this.llmModelPath)) {
return this.llmModelPath;
}
if (!this.isLlmModelAvailable()) {
if (!this.config.autoDownload) {
throw new Error(
`LLM model not found at ${this.getLlmModelPath()}. ` +
'Set autoDownload: true or manually download the model.'
);
}
this.llmModelPath = await this.downloadModel('llm', onProgress);
} else {
this.llmModelPath = this.getLlmModelPath();
}
return this.llmModelPath;
}
async ensureAllModels(onProgress?: IndexBuildCallback): Promise<{
embedModel: string;
llmModel: string;
}> {
const embedModel = await this.ensureEmbedModel(onProgress);
const llmModel = await this.ensureLlmModel(onProgress);
return { embedModel, llmModel };
}
getPublicModelInfo(modelType: 'embed' | 'llm'): {
name: string;
path: string;
available: boolean;
size: number;
description: string;
} {
const modelName = modelType === 'embed' ? this.config.embedModel : this.config.llmModel;
const modelPath = modelType === 'embed' ? this.getEmbedModelPath() : this.getLlmModelPath();
const modelInfo = this.getModelInfo(modelType, modelName);
return {
name: modelName,
path: modelPath,
available: fs.existsSync(modelPath),
size: modelInfo?.size ?? 0,
description: modelInfo?.description ?? 'Unknown model',
};
}
async clearModels(): Promise<void> {
const embedPath = this.getEmbedModelPath();
const llmPath = this.getLlmModelPath();
if (fs.existsSync(embedPath)) {
await fs.promises.unlink(embedPath);
}
if (fs.existsSync(llmPath)) {
await fs.promises.unlink(llmPath);
}
this.embedModelPath = null;
this.llmModelPath = null;
}
getConfig(): Required<LocalModelConfig> {
return { ...this.config };
}
}
export function formatBytes(bytes: number): string {
if (bytes === 0) return '0 Bytes';
const k = 1024;
const sizes = ['Bytes', 'KB', 'MB', 'GB'];
const i = Math.floor(Math.log(bytes) / Math.log(k));
return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`;
}
export function getDefaultModelDir(): string {
return DEFAULT_MODEL_DIR;
}
+177
View File
@@ -0,0 +1,177 @@
import type { RRFRanking } from './types.js';
import { DEFAULT_HYBRID_CONFIG } from './types.js';
export interface RankerResult {
skillName: string;
score: number;
}
export interface RRFInput {
source: string;
results: RankerResult[];
}
export function computeRRFScore(ranks: number[], k: number = DEFAULT_HYBRID_CONFIG.rrfK): number {
return ranks.reduce((sum, rank) => sum + 1 / (k + rank), 0);
}
export function fuseWithRRF(
rankerInputs: RRFInput[],
k: number = DEFAULT_HYBRID_CONFIG.rrfK
): RRFRanking[] {
const skillRanks = new Map<string, { source: string; rank: number }[]>();
for (const input of rankerInputs) {
const sortedResults = [...input.results].sort((a, b) => b.score - a.score);
for (let i = 0; i < sortedResults.length; i++) {
const result = sortedResults[i];
const rank = i + 1;
if (!skillRanks.has(result.skillName)) {
skillRanks.set(result.skillName, []);
}
skillRanks.get(result.skillName)!.push({
source: input.source,
rank,
});
}
}
const rankings: RRFRanking[] = [];
for (const [skillName, ranks] of skillRanks) {
const rankValues = ranks.map((r) => r.rank);
const rrfScore = computeRRFScore(rankValues, k);
rankings.push({
skillName,
rrfScore,
ranks,
});
}
rankings.sort((a, b) => b.rrfScore - a.rrfScore);
return rankings;
}
export function normalizeScores(results: RankerResult[]): RankerResult[] {
if (results.length === 0) return [];
const maxScore = Math.max(...results.map((r) => r.score));
const minScore = Math.min(...results.map((r) => r.score));
const range = maxScore - minScore;
if (range === 0) {
return results.map((r) => ({ ...r, score: 1 }));
}
return results.map((r) => ({
...r,
score: (r.score - minScore) / range,
}));
}
export function weightedCombine(
results: RRFInput[],
weights: Record<string, number>
): RankerResult[] {
const combinedScores = new Map<string, number>();
for (const input of results) {
const weight = weights[input.source] ?? 1;
const normalizedResults = normalizeScores(input.results);
for (const result of normalizedResults) {
const current = combinedScores.get(result.skillName) ?? 0;
combinedScores.set(result.skillName, current + result.score * weight);
}
}
return Array.from(combinedScores, ([skillName, score]) => ({ skillName, score }))
.sort((a, b) => b.score - a.score);
}
export function applyPositionAwareBlending(
retrievalScores: Map<string, number>,
rerankerScores: Map<string, number>,
sortedSkillNames: string[],
config = DEFAULT_HYBRID_CONFIG.positionBlending
): Map<string, number> {
const blendedScores = new Map<string, number>();
for (let i = 0; i < sortedSkillNames.length; i++) {
const skillName = sortedSkillNames[i];
const rank = i + 1;
let weights: { retrieval: number; reranker: number };
if (rank <= 3) {
weights = config.top3;
} else if (rank <= 10) {
weights = config.top10;
} else {
weights = config.rest;
}
const retrievalScore = retrievalScores.get(skillName) ?? 0;
const rerankerScore = rerankerScores.get(skillName) ?? 0;
const blendedScore =
retrievalScore * weights.retrieval + rerankerScore * weights.reranker;
blendedScores.set(skillName, blendedScore);
}
return blendedScores;
}
export function getRankFromScore(
skillName: string,
rankedResults: RankerResult[]
): number {
const sortedResults = [...rankedResults].sort((a, b) => b.score - a.score);
const index = sortedResults.findIndex((r) => r.skillName === skillName);
return index === -1 ? sortedResults.length + 1 : index + 1;
}
export function mergeRankings(
primaryRankings: RRFRanking[],
secondaryRankings: RRFRanking[],
primaryWeight: number = 0.7
): RRFRanking[] {
const secondaryWeight = 1 - primaryWeight;
const mergedScores = new Map<string, { score: number; ranks: { source: string; rank: number }[] }>();
for (const ranking of primaryRankings) {
mergedScores.set(ranking.skillName, {
score: ranking.rrfScore * primaryWeight,
ranks: [...ranking.ranks],
});
}
for (const ranking of secondaryRankings) {
const existing = mergedScores.get(ranking.skillName);
if (existing) {
existing.score += ranking.rrfScore * secondaryWeight;
existing.ranks = [...existing.ranks, ...ranking.ranks];
} else {
mergedScores.set(ranking.skillName, {
score: ranking.rrfScore * secondaryWeight,
ranks: [...ranking.ranks],
});
}
}
const merged: RRFRanking[] = [];
for (const [skillName, data] of mergedScores) {
merged.push({
skillName,
rrfScore: data.score,
ranks: data.ranks,
});
}
merged.sort((a, b) => b.rrfScore - a.rrfScore);
return merged;
}
+177
View File
@@ -0,0 +1,177 @@
import { z } from 'zod';
import type { SearchResult } from '../recommend/types.js';
export const LocalModelConfigSchema = z.object({
embedModel: z.string().default('nomic-embed-text-v1.5.Q4_K_M.gguf'),
llmModel: z.string().default('gemma-2b-it-Q4_K_M.gguf'),
modelDir: z.string().optional(),
autoDownload: z.boolean().default(true),
gpuLayers: z.number().default(0),
});
export type LocalModelConfig = z.infer<typeof LocalModelConfigSchema>;
export const SkillChunkSchema = z.object({
content: z.string(),
startLine: z.number(),
endLine: z.number(),
tokenCount: z.number(),
});
export type SkillChunk = z.infer<typeof SkillChunkSchema>;
export interface SkillEmbedding {
skillName: string;
vector: Float32Array;
textContent: string;
chunks?: {
content: string;
vector: Float32Array;
startLine: number;
endLine: number;
}[];
generatedAt: string;
}
export interface VectorSearchResult {
skillName: string;
similarity: number;
matchedChunk?: {
content: string;
startLine: number;
};
}
export interface ExpandedQuery {
original: string;
variations: string[];
weights: number[];
}
export interface RRFRanking {
skillName: string;
rrfScore: number;
ranks: {
source: string;
rank: number;
}[];
}
export interface HybridSearchOptions {
query: string;
limit?: number;
enableExpansion?: boolean;
enableReranking?: boolean;
semanticWeight?: number;
keywordWeight?: number;
rrfK?: number;
positionAwareBlending?: boolean;
}
export interface HybridSearchResult extends SearchResult {
hybridScore: number;
vectorSimilarity?: number;
keywordScore?: number;
rrfScore?: number;
rerankerScore?: number;
expandedTerms?: string[];
blendingWeights?: {
retrieval: number;
reranker: number;
};
}
export interface HybridSearchResponse {
results: HybridSearchResult[];
query: {
original: string;
expanded?: ExpandedQuery;
};
timing: {
totalMs: number;
embeddingMs?: number;
vectorSearchMs?: number;
keywordSearchMs?: number;
fusionMs?: number;
rerankingMs?: number;
};
stats: {
candidatesFromVector: number;
candidatesFromKeyword: number;
totalMerged: number;
reranked: number;
};
}
export interface EmbeddingServiceStats {
totalSkillsIndexed: number;
totalChunks: number;
indexSizeBytes: number;
lastIndexedAt: string;
modelName: string;
embeddingDimensions: number;
}
export interface VectorStoreConfig {
dbPath: string;
tableName?: string;
dimensions?: number;
}
export interface IndexBuildProgress {
phase: 'downloading' | 'loading' | 'embedding' | 'storing' | 'complete';
current: number;
total: number;
skillName?: string;
message?: string;
}
export type IndexBuildCallback = (progress: IndexBuildProgress) => void;
export const MODEL_REGISTRY = {
embeddings: {
'nomic-embed-text-v1.5.Q4_K_M.gguf': {
url: 'https://huggingface.co/nomic-ai/nomic-embed-text-v1.5-GGUF/resolve/main/nomic-embed-text-v1.5.Q4_K_M.gguf',
size: 547000000,
dimensions: 768,
description: 'Nomic Embed Text v1.5 - High quality embeddings',
},
},
llm: {
'gemma-2b-it-Q4_K_M.gguf': {
url: 'https://huggingface.co/bartowski/gemma-2-2b-it-GGUF/resolve/main/gemma-2-2b-it-Q4_K_M.gguf',
size: 1500000000,
description: 'Gemma 2 2B Instruct - Fast query expansion and reranking',
},
},
} as const;
export const DEFAULT_CHUNKING_CONFIG = {
maxTokens: 800,
overlapPercent: 15,
minChunkSize: 100,
} as const;
export const DEFAULT_HYBRID_CONFIG = {
rrfK: 60,
semanticWeight: 0.5,
keywordWeight: 0.5,
rerankTopN: 30,
positionBlending: {
top3: { retrieval: 0.75, reranker: 0.25 },
top10: { retrieval: 0.6, reranker: 0.4 },
rest: { retrieval: 0.4, reranker: 0.6 },
},
expansionCacheTtlMs: 5 * 60 * 1000,
} as const;
export interface RerankerInput {
query: string;
skillName: string;
skillDescription: string;
skillTags: string[];
}
export interface RerankerOutput {
skillName: string;
score: number;
reasoning?: string;
}
+510
View File
@@ -0,0 +1,510 @@
import * as fs from 'node:fs';
import * as path from 'node:path';
import * as os from 'node:os';
import type {
SkillEmbedding,
VectorSearchResult,
VectorStoreConfig,
EmbeddingServiceStats,
IndexBuildCallback,
} from './types.js';
import { EmbeddingService } from './embeddings.js';
const DEFAULT_DB_PATH = path.join(os.homedir(), '.skillkit', 'search.db');
const DEFAULT_TABLE_NAME = 'skill_embeddings';
const DEFAULT_DIMENSIONS = 768;
export class VectorStore {
private config: Required<VectorStoreConfig>;
private db: unknown = null;
private initialized = false;
private usingSqliteVec = false;
private embeddings: Map<string, SkillEmbedding> = new Map();
private embeddingService: EmbeddingService;
constructor(config: Partial<VectorStoreConfig> = {}, embeddingService?: EmbeddingService) {
const tableName = config.tableName ?? DEFAULT_TABLE_NAME;
if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(tableName)) {
throw new Error(`Invalid table name: ${tableName}. Must be a valid SQL identifier.`);
}
this.config = {
dbPath: config.dbPath ?? DEFAULT_DB_PATH,
tableName,
dimensions: config.dimensions ?? DEFAULT_DIMENSIONS,
};
this.embeddingService = embeddingService ?? new EmbeddingService();
}
async initialize(): Promise<void> {
if (this.initialized) return;
const dbDir = path.dirname(this.config.dbPath);
if (!fs.existsSync(dbDir)) {
await fs.promises.mkdir(dbDir, { recursive: true });
}
try {
const BetterSqlite3Module = await import('better-sqlite3');
const BetterSqlite3 = BetterSqlite3Module.default || BetterSqlite3Module;
this.db = new BetterSqlite3(this.config.dbPath);
try {
const sqliteVec = await import('sqlite-vec');
sqliteVec.load(this.db as Parameters<typeof sqliteVec.load>[0]);
this.usingSqliteVec = true;
await this.initializeSqliteVecTables();
} catch {
this.usingSqliteVec = false;
await this.initializeFallbackTables();
}
await this.loadEmbeddingsFromDb();
this.initialized = true;
} catch (error) {
if (
error instanceof Error &&
(error.message.includes("Cannot find package 'better-sqlite3'") ||
error.message.includes("Cannot find module 'better-sqlite3'"))
) {
this.initialized = true;
this.usingSqliteVec = false;
return;
}
throw error;
}
}
private async initializeSqliteVecTables(): Promise<void> {
const db = this.db as {
exec(sql: string): void;
prepare(sql: string): { run(...args: unknown[]): void };
};
db.exec(`
CREATE TABLE IF NOT EXISTS ${this.config.tableName}_meta (
skill_name TEXT PRIMARY KEY,
text_content TEXT NOT NULL,
generated_at TEXT NOT NULL,
chunk_count INTEGER DEFAULT 0
)
`);
db.exec(`
CREATE VIRTUAL TABLE IF NOT EXISTS ${this.config.tableName}_vec USING vec0(
skill_name TEXT PRIMARY KEY,
embedding float[${this.config.dimensions}]
)
`);
db.exec(`
CREATE TABLE IF NOT EXISTS ${this.config.tableName}_chunks (
id INTEGER PRIMARY KEY AUTOINCREMENT,
skill_name TEXT NOT NULL,
content TEXT NOT NULL,
start_line INTEGER NOT NULL,
end_line INTEGER NOT NULL,
FOREIGN KEY (skill_name) REFERENCES ${this.config.tableName}_meta(skill_name)
)
`);
db.exec(`
CREATE VIRTUAL TABLE IF NOT EXISTS ${this.config.tableName}_chunks_vec USING vec0(
chunk_id INTEGER PRIMARY KEY,
embedding float[${this.config.dimensions}]
)
`);
}
private async initializeFallbackTables(): Promise<void> {
const db = this.db as { exec(sql: string): void };
db.exec(`
CREATE TABLE IF NOT EXISTS ${this.config.tableName} (
skill_name TEXT PRIMARY KEY,
text_content TEXT NOT NULL,
vector BLOB NOT NULL,
generated_at TEXT NOT NULL
)
`);
db.exec(`
CREATE TABLE IF NOT EXISTS ${this.config.tableName}_chunks (
id INTEGER PRIMARY KEY AUTOINCREMENT,
skill_name TEXT NOT NULL,
content TEXT NOT NULL,
vector BLOB NOT NULL,
start_line INTEGER NOT NULL,
end_line INTEGER NOT NULL
)
`);
db.exec(`
CREATE INDEX IF NOT EXISTS idx_${this.config.tableName}_skill
ON ${this.config.tableName}_chunks(skill_name)
`);
}
private async loadEmbeddingsFromDb(): Promise<void> {
if (!this.db) return;
const db = this.db as {
prepare(sql: string): { all(): Array<{
skill_name: string;
text_content: string;
vector?: Buffer;
generated_at: string;
}> };
};
try {
if (this.usingSqliteVec) {
const rows = db.prepare(`
SELECT skill_name, text_content, generated_at
FROM ${this.config.tableName}_meta
`).all();
for (const row of rows) {
this.embeddings.set(row.skill_name, {
skillName: row.skill_name,
textContent: row.text_content,
vector: new Float32Array(this.config.dimensions),
generatedAt: row.generated_at,
});
}
} else {
const rows = db.prepare(`
SELECT skill_name, text_content, vector, generated_at
FROM ${this.config.tableName}
`).all();
for (const row of rows) {
if (row.vector) {
this.embeddings.set(row.skill_name, {
skillName: row.skill_name,
textContent: row.text_content,
vector: new Float32Array(row.vector.buffer),
generatedAt: row.generated_at,
});
}
}
}
} catch {
// Failed to load embeddings from DB - will start with empty in-memory store
}
}
async store(embedding: SkillEmbedding): Promise<void> {
await this.initialize();
this.embeddings.set(embedding.skillName, embedding);
if (!this.db) return;
const db = this.db as {
prepare(sql: string): {
run(...args: unknown[]): { lastInsertRowid?: number };
};
};
if (this.usingSqliteVec) {
db.prepare(`
INSERT OR REPLACE INTO ${this.config.tableName}_meta
(skill_name, text_content, generated_at, chunk_count)
VALUES (?, ?, ?, ?)
`).run(
embedding.skillName,
embedding.textContent,
embedding.generatedAt,
embedding.chunks?.length ?? 0
);
db.prepare(`
INSERT OR REPLACE INTO ${this.config.tableName}_vec
(skill_name, embedding)
VALUES (?, ?)
`).run(embedding.skillName, Buffer.from(embedding.vector.buffer));
if (embedding.chunks) {
db.prepare(`
DELETE FROM ${this.config.tableName}_chunks WHERE skill_name = ?
`).run(embedding.skillName);
for (const chunk of embedding.chunks) {
const result = db.prepare(`
INSERT INTO ${this.config.tableName}_chunks
(skill_name, content, start_line, end_line)
VALUES (?, ?, ?, ?)
`).run(embedding.skillName, chunk.content, chunk.startLine, chunk.endLine);
const rowId = result.lastInsertRowid ?? 0;
db.prepare(`
INSERT INTO ${this.config.tableName}_chunks_vec
(chunk_id, embedding)
VALUES (?, ?)
`).run(rowId, Buffer.from(chunk.vector.buffer));
}
}
} else {
db.prepare(`
INSERT OR REPLACE INTO ${this.config.tableName}
(skill_name, text_content, vector, generated_at)
VALUES (?, ?, ?, ?)
`).run(
embedding.skillName,
embedding.textContent,
Buffer.from(embedding.vector.buffer),
embedding.generatedAt
);
if (embedding.chunks) {
db.prepare(`
DELETE FROM ${this.config.tableName}_chunks WHERE skill_name = ?
`).run(embedding.skillName);
for (const chunk of embedding.chunks) {
db.prepare(`
INSERT INTO ${this.config.tableName}_chunks
(skill_name, content, vector, start_line, end_line)
VALUES (?, ?, ?, ?, ?)
`).run(
embedding.skillName,
chunk.content,
Buffer.from(chunk.vector.buffer),
chunk.startLine,
chunk.endLine
);
}
}
}
}
async storeBatch(
embeddings: SkillEmbedding[],
onProgress?: IndexBuildCallback
): Promise<void> {
await this.initialize();
const total = embeddings.length;
for (let i = 0; i < embeddings.length; i++) {
const embedding = embeddings[i];
onProgress?.({
phase: 'storing',
current: i + 1,
total,
skillName: embedding.skillName,
message: `Storing embedding ${i + 1}/${total}: ${embedding.skillName}`,
});
await this.store(embedding);
}
onProgress?.({
phase: 'complete',
current: total,
total,
message: `Stored ${total} embeddings`,
});
}
async search(
queryVector: Float32Array,
limit: number = 10
): Promise<VectorSearchResult[]> {
await this.initialize();
if (this.usingSqliteVec && this.db) {
return this.searchWithSqliteVec(queryVector, limit);
}
return this.searchInMemory(queryVector, limit);
}
private async searchWithSqliteVec(
queryVector: Float32Array,
limit: number
): Promise<VectorSearchResult[]> {
const db = this.db as {
prepare(sql: string): {
all(...args: unknown[]): Array<{ skill_name: string; distance: number }>;
};
};
const rows = db.prepare(`
SELECT skill_name, distance
FROM ${this.config.tableName}_vec
WHERE embedding MATCH ?
ORDER BY distance
LIMIT ?
`).all(Buffer.from(queryVector.buffer), limit);
return rows.map((row) => ({
skillName: row.skill_name,
similarity: 1 - row.distance,
}));
}
private searchInMemory(
queryVector: Float32Array,
limit: number
): VectorSearchResult[] {
const results: VectorSearchResult[] = [];
for (const [skillName, embedding] of this.embeddings) {
const similarity = this.embeddingService.cosineSimilarity(queryVector, embedding.vector);
results.push({ skillName, similarity });
}
results.sort((a, b) => b.similarity - a.similarity);
return results.slice(0, limit);
}
async searchChunks(
queryVector: Float32Array,
limit: number = 10
): Promise<VectorSearchResult[]> {
await this.initialize();
const results: VectorSearchResult[] = [];
for (const [skillName, embedding] of this.embeddings) {
if (!embedding.chunks || embedding.chunks.length === 0) {
const similarity = this.embeddingService.cosineSimilarity(queryVector, embedding.vector);
results.push({ skillName, similarity });
continue;
}
let bestChunk: { similarity: number; content: string; startLine: number } | null = null;
for (const chunk of embedding.chunks) {
const similarity = this.embeddingService.cosineSimilarity(queryVector, chunk.vector);
if (!bestChunk || similarity > bestChunk.similarity) {
bestChunk = {
similarity,
content: chunk.content,
startLine: chunk.startLine,
};
}
}
if (bestChunk) {
results.push({
skillName,
similarity: bestChunk.similarity,
matchedChunk: {
content: bestChunk.content,
startLine: bestChunk.startLine,
},
});
}
}
results.sort((a, b) => b.similarity - a.similarity);
return results.slice(0, limit);
}
has(skillName: string): boolean {
return this.embeddings.has(skillName);
}
get(skillName: string): SkillEmbedding | undefined {
return this.embeddings.get(skillName);
}
async delete(skillName: string): Promise<void> {
await this.initialize();
this.embeddings.delete(skillName);
if (!this.db) return;
const db = this.db as {
prepare(sql: string): { run(...args: unknown[]): void };
};
if (this.usingSqliteVec) {
db.prepare(`DELETE FROM ${this.config.tableName}_meta WHERE skill_name = ?`).run(skillName);
db.prepare(`DELETE FROM ${this.config.tableName}_vec WHERE skill_name = ?`).run(skillName);
db.prepare(`
DELETE FROM ${this.config.tableName}_chunks_vec
WHERE chunk_id IN (
SELECT id FROM ${this.config.tableName}_chunks WHERE skill_name = ?
)
`).run(skillName);
} else {
db.prepare(`DELETE FROM ${this.config.tableName} WHERE skill_name = ?`).run(skillName);
}
db.prepare(`DELETE FROM ${this.config.tableName}_chunks WHERE skill_name = ?`).run(skillName);
}
async clear(): Promise<void> {
await this.initialize();
this.embeddings.clear();
if (!this.db) return;
const db = this.db as { exec(sql: string): void };
if (this.usingSqliteVec) {
db.exec(`DELETE FROM ${this.config.tableName}_meta`);
db.exec(`DELETE FROM ${this.config.tableName}_vec`);
db.exec(`DELETE FROM ${this.config.tableName}_chunks_vec`);
} else {
db.exec(`DELETE FROM ${this.config.tableName}`);
}
db.exec(`DELETE FROM ${this.config.tableName}_chunks`);
}
getStats(): EmbeddingServiceStats {
let indexSizeBytes = 0;
let totalChunks = 0;
for (const embedding of this.embeddings.values()) {
indexSizeBytes += embedding.vector.byteLength;
indexSizeBytes += embedding.textContent.length * 2;
if (embedding.chunks) {
totalChunks += embedding.chunks.length;
for (const chunk of embedding.chunks) {
indexSizeBytes += chunk.vector.byteLength;
indexSizeBytes += chunk.content.length * 2;
}
}
}
return {
totalSkillsIndexed: this.embeddings.size,
totalChunks,
indexSizeBytes,
lastIndexedAt: new Date().toISOString(),
modelName: 'nomic-embed-text-v1.5',
embeddingDimensions: this.config.dimensions,
};
}
isInitialized(): boolean {
return this.initialized;
}
isUsingSqliteVec(): boolean {
return this.usingSqliteVec;
}
getEmbeddingCount(): number {
return this.embeddings.size;
}
async close(): Promise<void> {
if (this.db && typeof (this.db as { close?: () => void }).close === 'function') {
(this.db as { close: () => void }).close();
}
this.db = null;
this.initialized = false;
}
}
export function createVectorStore(
config?: Partial<VectorStoreConfig>,
embeddingService?: EmbeddingService
): VectorStore {
return new VectorStore(config, embeddingService);
}
+4 -3
View File
@@ -1,5 +1,5 @@
import { existsSync, readdirSync, readFileSync } from 'node:fs';
import { join, basename } from 'node:path';
import { join, basename, resolve, sep } from 'node:path';
import { parse as parseYaml } from 'yaml';
import { SkillFrontmatter, SkillMetadata, type Skill, type SkillLocation } from './types.js';
@@ -391,6 +391,7 @@ export function validateSkill(skillPath: string): { valid: boolean; errors: stri
}
export function isPathInside(child: string, parent: string): boolean {
const relative = child.replace(parent, '');
return !relative.startsWith('..') && !relative.includes('/..');
const resolved = resolve(child);
const resolvedParent = resolve(parent);
return resolved === resolvedParent || resolved.startsWith(resolvedParent + sep);
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/mcp-memory",
"version": "1.9.0",
"version": "1.11.0",
"description": "MCP (Model Context Protocol) server for SkillKit persistent memory",
"type": "module",
"main": "./dist/index.js",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/memory",
"version": "1.9.0",
"version": "1.11.0",
"description": "CozoDB-backed semantic memory with embeddings for SkillKit",
"type": "module",
"main": "./dist/index.js",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/mesh",
"version": "1.9.0",
"version": "1.11.0",
"description": "Peer mesh network for multi-machine agent distribution",
"type": "module",
"main": "./dist/index.js",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/messaging",
"version": "1.9.0",
"version": "1.11.0",
"description": "Inter-agent messaging system for SkillKit",
"type": "module",
"main": "./dist/index.js",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/resources",
"version": "1.9.0",
"version": "1.11.0",
"description": "Bundled resources for SkillKit - agents, commands, profiles, guidelines, and hooks",
"type": "module",
"main": "./dist/index.js",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/tui",
"version": "1.9.0",
"version": "1.11.0",
"description": "Unified Terminal UI for SkillKit - Built on OpenTUI",
"type": "module",
"main": "./dist/index.js",
+1320
View File
File diff suppressed because it is too large Load Diff
+4 -3
View File
@@ -1,5 +1,5 @@
import { existsSync, readdirSync, readFileSync } from 'node:fs';
import { join, basename } from 'node:path';
import { join, basename, resolve, sep } from 'node:path';
import { parse as parseYaml } from 'yaml';
import { SkillFrontmatter, SkillMetadata, type Skill, type SkillLocation } from './types.js';
@@ -328,6 +328,7 @@ export function validateSkill(skillPath: string): { valid: boolean; errors: stri
}
export function isPathInside(child: string, parent: string): boolean {
const relative = child.replace(parent, '');
return !relative.startsWith('..') && !relative.includes('/..');
const resolved = resolve(child);
const resolvedParent = resolve(parent);
return resolved === resolvedParent || resolved.startsWith(resolvedParent + sep);
}