mirror of
https://github.com/rohitg00/skillkit.git
synced 2026-11-20 12:23:29 +00:00
Compare commits
18
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
549a21ad84 | ||
|
|
109f00cd95 | ||
|
|
e3d7e0e28f | ||
|
|
6cbbdabf59 | ||
|
|
c1c179217d | ||
|
|
de4425f440 | ||
|
|
8121c2bbac | ||
|
|
3565daa7f1 | ||
|
|
8496e3c63c | ||
|
|
847af0f7ab | ||
|
|
34e8cd0b61 | ||
|
|
cbd9fcd679 | ||
|
|
f9e31fedc8 | ||
|
|
12ed10d170 | ||
|
|
eebaa710f7 | ||
|
|
eae5accf36 | ||
|
|
e41b0cd8a3 | ||
|
|
21df323134 |
@@ -142,8 +142,25 @@ Filter by task, category, or minimum score:
|
||||
skillkit recommend --search "auth" # Task-based search
|
||||
skillkit recommend --category security # Category filter
|
||||
skillkit recommend --min-score 80 # Quality threshold
|
||||
skillkit recommend --explain # Show WHY skills match
|
||||
skillkit recommend --reasoning # Use LLM-based search
|
||||
```
|
||||
|
||||
### Hierarchical Skill Tree
|
||||
|
||||
Browse skills organized in a navigable taxonomy:
|
||||
|
||||
```bash
|
||||
skillkit tree # Show full tree
|
||||
skillkit tree Frontend # Show Frontend subtree
|
||||
skillkit tree "Frontend > React" # Navigate to subcategory
|
||||
skillkit tree --generate # Generate tree from index
|
||||
skillkit tree --stats # Show tree statistics
|
||||
skillkit tree --depth 2 # Limit display depth
|
||||
```
|
||||
|
||||
**Categories:** Development, Frontend, Backend, Mobile, DevOps, Testing, Security, AI/ML, Database, Tooling, Documentation, Performance
|
||||
|
||||
### Session Memory System
|
||||
|
||||
Your AI agents learn, but that knowledge dies with the session. SkillKit captures learnings and makes them persistent:
|
||||
@@ -190,7 +207,7 @@ skillkit ui
|
||||
skillkit
|
||||
```
|
||||
|
||||
**Navigation:** `h` Home | `b` Browse | `r` Recommend | `t` Translate | `c` Context | `l` List | `s` Sync | `q` Quit
|
||||
**Navigation:** `h` Home | `m` Marketplace | `b` Browse | `v` Tree View | `r` Recommend | `t` Translate | `c` Context | `l` List | `s` Sync | `q` Quit
|
||||
|
||||
### Skill Testing Framework
|
||||
|
||||
@@ -298,6 +315,10 @@ skillkit status # Show skill and agent status
|
||||
|
||||
```bash
|
||||
skillkit recommend # Get smart recommendations
|
||||
skillkit recommend --explain # Show reasoning for matches
|
||||
skillkit recommend --reasoning # Use LLM-based discovery
|
||||
skillkit tree # Browse hierarchical taxonomy
|
||||
skillkit tree --generate # Generate tree from index
|
||||
skillkit marketplace # Browse skill marketplace
|
||||
skillkit marketplace search # Search marketplace
|
||||
skillkit find <query> # Quick skill search
|
||||
@@ -428,11 +449,31 @@ skillkit methodology load # Load a methodology
|
||||
### Publishing & Sharing
|
||||
|
||||
```bash
|
||||
skillkit publish # Publish skill to marketplace
|
||||
skillkit publish # Generate well-known hosting structure
|
||||
skillkit publish submit # Submit to SkillKit marketplace
|
||||
skillkit create # Create new skill
|
||||
skillkit init # Initialize in project
|
||||
```
|
||||
|
||||
#### Self-Hosting Skills (RFC 8615)
|
||||
|
||||
Generate a well-known URI structure to host skills on your own domain:
|
||||
|
||||
```bash
|
||||
# Generate hosting structure
|
||||
skillkit publish ./my-skills --output ./public
|
||||
|
||||
# Users install from your domain
|
||||
skillkit add https://your-domain.com
|
||||
```
|
||||
|
||||
This creates:
|
||||
```
|
||||
.well-known/skills/
|
||||
index.json # Skill manifest
|
||||
my-skill/SKILL.md # Skill files
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
```bash
|
||||
@@ -491,8 +532,29 @@ import {
|
||||
|
||||
// Recommendations
|
||||
RecommendationEngine,
|
||||
ReasoningRecommendationEngine,
|
||||
analyzeProject,
|
||||
|
||||
// Tree & Taxonomy
|
||||
TreeGenerator,
|
||||
generateSkillTree,
|
||||
loadTree,
|
||||
buildSkillGraph,
|
||||
getRelatedSkills,
|
||||
|
||||
// Reasoning Engine
|
||||
ReasoningEngine,
|
||||
createReasoningEngine,
|
||||
|
||||
// Connectors (Tool-Agnostic Placeholders)
|
||||
detectPlaceholders,
|
||||
replacePlaceholders,
|
||||
suggestMappingsFromMcp,
|
||||
|
||||
// Execution Flow
|
||||
ExecutionManager,
|
||||
detectExecutionMode,
|
||||
|
||||
// Context
|
||||
ContextManager,
|
||||
syncToAllAgents,
|
||||
@@ -516,10 +578,20 @@ import {
|
||||
const skill = await translateSkill(skillContent, 'cursor');
|
||||
console.log(skill.content);
|
||||
|
||||
// Example: Get recommendations
|
||||
const engine = new RecommendationEngine();
|
||||
// Example: Get recommendations with reasoning
|
||||
const engine = new ReasoningRecommendationEngine();
|
||||
await engine.initReasoning();
|
||||
const profile = await analyzeProject('./my-project');
|
||||
const recs = engine.recommend(profile);
|
||||
const recs = await engine.recommendWithReasoning(profile, { reasoning: true });
|
||||
|
||||
// Example: Browse skill tree
|
||||
const tree = generateSkillTree(skills);
|
||||
console.log(tree.rootNode.children); // Categories
|
||||
|
||||
// Example: Detect execution mode
|
||||
const mode = detectExecutionMode();
|
||||
console.log(mode.mode); // 'standalone' or 'enhanced'
|
||||
console.log(mode.capabilities); // Available MCP capabilities
|
||||
```
|
||||
|
||||
## Skill Sources & Attribution
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "skillkit",
|
||||
"version": "1.8.0",
|
||||
"version": "1.10.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": {
|
||||
|
||||
@@ -48,10 +48,12 @@ import {
|
||||
AICommand,
|
||||
AuditCommand,
|
||||
PublishCommand,
|
||||
PublishSubmitCommand,
|
||||
AgentCommand,
|
||||
AgentListCommand,
|
||||
AgentShowCommand,
|
||||
AgentCreateCommand,
|
||||
AgentFromSkillCommand,
|
||||
AgentTranslateCommand,
|
||||
AgentSyncCommand,
|
||||
AgentValidateCommand,
|
||||
@@ -95,6 +97,7 @@ import {
|
||||
GuidelineDisableCommand,
|
||||
GuidelineCreateCommand,
|
||||
GuidelineRemoveCommand,
|
||||
TreeCommand,
|
||||
} from '@skillkit/cli';
|
||||
|
||||
const __filename = fileURLToPath(import.meta.url);
|
||||
@@ -149,10 +152,12 @@ cli.register(CommandCmd);
|
||||
cli.register(AICommand);
|
||||
cli.register(AuditCommand);
|
||||
cli.register(PublishCommand);
|
||||
cli.register(PublishSubmitCommand);
|
||||
cli.register(AgentCommand);
|
||||
cli.register(AgentListCommand);
|
||||
cli.register(AgentShowCommand);
|
||||
cli.register(AgentCreateCommand);
|
||||
cli.register(AgentFromSkillCommand);
|
||||
cli.register(AgentTranslateCommand);
|
||||
cli.register(AgentSyncCommand);
|
||||
cli.register(AgentValidateCommand);
|
||||
@@ -213,4 +218,6 @@ cli.register(GuidelineDisableCommand);
|
||||
cli.register(GuidelineCreateCommand);
|
||||
cli.register(GuidelineRemoveCommand);
|
||||
|
||||
cli.register(TreeCommand);
|
||||
|
||||
cli.runExit(process.argv.slice(2));
|
||||
|
||||
@@ -87,6 +87,151 @@ import { RecommendationEngine, analyzeProject } from '@skillkit/core/recommend'
|
||||
const engine = new RecommendationEngine()
|
||||
const profile = await analyzeProject('./my-project')
|
||||
const recommendations = engine.recommend(profile)
|
||||
|
||||
// Recommendations with scores and reasons
|
||||
recommendations.forEach(rec => {
|
||||
console.log(`${rec.score}% - ${rec.skill.name}`)
|
||||
console.log(`Reasons: ${rec.reasons.join(', ')}`)
|
||||
})
|
||||
```
|
||||
|
||||
## Primer (Auto-Generate Instructions)
|
||||
|
||||
```typescript
|
||||
import { promises as fs } from 'node:fs'
|
||||
import { analyzeProject, generateInstructions } from '@skillkit/core'
|
||||
|
||||
// Analyze project
|
||||
const analysis = await analyzeProject('./my-project')
|
||||
console.log(analysis.techStack)
|
||||
// { framework: 'Next.js', language: 'TypeScript', styling: 'Tailwind' }
|
||||
|
||||
// Generate instructions for specific agents
|
||||
const instructions = await generateInstructions(analysis, {
|
||||
agents: ['claude', 'cursor', 'windsurf'],
|
||||
includeExamples: true,
|
||||
tone: 'detailed',
|
||||
})
|
||||
|
||||
// Write to files
|
||||
for (const [agent, content] of Object.entries(instructions)) {
|
||||
await fs.writeFile(`.${agent}/instructions.md`, content)
|
||||
}
|
||||
```
|
||||
|
||||
## Mesh Network
|
||||
|
||||
```typescript
|
||||
import { MeshHost, PeerIdentity } from '@skillkit/mesh'
|
||||
|
||||
// Generate identity
|
||||
const identity = await PeerIdentity.generate()
|
||||
|
||||
// Create mesh host
|
||||
const host = new MeshHost({
|
||||
hostId: 'my-workstation',
|
||||
identity,
|
||||
security: { mode: 'secure' },
|
||||
})
|
||||
|
||||
await host.start()
|
||||
|
||||
// Send message to peer
|
||||
await host.send('peer-fingerprint', {
|
||||
type: 'skill-sync',
|
||||
payload: { skills: ['react-patterns'] },
|
||||
})
|
||||
|
||||
// Listen for messages
|
||||
host.on('message', (msg) => {
|
||||
console.log('Received:', msg.type, 'from', msg.from)
|
||||
})
|
||||
```
|
||||
|
||||
## Inter-Agent Messaging
|
||||
|
||||
```typescript
|
||||
import { MessagingClient } from '@skillkit/messaging'
|
||||
|
||||
// Create messaging client (host is a MeshHost instance from the example above)
|
||||
const messaging = new MessagingClient({
|
||||
meshHost: host, // See MeshHost setup in "Mesh Network" section above
|
||||
storagePath: '~/.skillkit/messages',
|
||||
})
|
||||
|
||||
await messaging.init()
|
||||
|
||||
// Send a message
|
||||
await messaging.send({
|
||||
to: 'claude@laptop',
|
||||
subject: 'Code review completed',
|
||||
body: 'I reviewed the auth module...',
|
||||
priority: 'normal',
|
||||
})
|
||||
|
||||
// Listen for new messages
|
||||
messaging.on('message', (msg) => {
|
||||
console.log('New message from:', msg.from)
|
||||
console.log('Subject:', msg.subject)
|
||||
})
|
||||
|
||||
// Get inbox
|
||||
const inbox = await messaging.getInbox({ unread: true })
|
||||
```
|
||||
|
||||
## Workflow Orchestration
|
||||
|
||||
```typescript
|
||||
import { WorkflowEngine, WorkflowStep } from '@skillkit/core'
|
||||
|
||||
// Define workflow
|
||||
const workflow = {
|
||||
name: 'feature-development',
|
||||
steps: [
|
||||
{ skill: 'tdd-workflow', action: 'write-tests' },
|
||||
{ skill: 'code-implementation', action: 'implement' },
|
||||
{ skill: 'code-review', action: 'review' },
|
||||
{ skill: 'documentation', action: 'update-docs' },
|
||||
],
|
||||
}
|
||||
|
||||
// Execute workflow
|
||||
const engine = new WorkflowEngine()
|
||||
const result = await engine.run(workflow)
|
||||
|
||||
console.log('Workflow completed:', result.status)
|
||||
console.log('Steps executed:', result.steps.length)
|
||||
```
|
||||
|
||||
## Skill Testing
|
||||
|
||||
```typescript
|
||||
import { SkillTestRunner, SkillTest } from '@skillkit/core'
|
||||
|
||||
// Define test
|
||||
const test: SkillTest = {
|
||||
name: 'pdf-processing',
|
||||
setup: async () => {
|
||||
// Setup test environment
|
||||
},
|
||||
assertions: [
|
||||
{
|
||||
type: 'file_exists',
|
||||
path: './output.pdf',
|
||||
},
|
||||
{
|
||||
type: 'content_includes',
|
||||
text: 'Expected content',
|
||||
},
|
||||
],
|
||||
}
|
||||
|
||||
// Run test
|
||||
const runner = new SkillTestRunner()
|
||||
const result = await runner.run(test)
|
||||
|
||||
console.log('Test passed:', result.passed)
|
||||
console.log('Assertions:', result.assertions)
|
||||
```
|
||||
|
||||
## Types
|
||||
@@ -99,6 +244,15 @@ interface Skill {
|
||||
content: string
|
||||
metadata: SkillMetadata
|
||||
enabled: boolean
|
||||
agent: string
|
||||
}
|
||||
|
||||
interface SkillMetadata {
|
||||
version?: string
|
||||
author?: string
|
||||
tags?: string[]
|
||||
dependencies?: string[]
|
||||
quality?: QualityScore
|
||||
}
|
||||
|
||||
interface QualityScore {
|
||||
@@ -114,4 +268,155 @@ interface Recommendation {
|
||||
score: number
|
||||
reasons: string[]
|
||||
}
|
||||
|
||||
interface ProjectAnalysis {
|
||||
techStack: {
|
||||
framework?: string
|
||||
language: string
|
||||
styling?: string
|
||||
testing?: string
|
||||
packageManager: string
|
||||
}
|
||||
patterns: {
|
||||
architecture: string
|
||||
codeStyle: Record<string, any>
|
||||
directory: string
|
||||
}
|
||||
dependencies: Record<string, string>
|
||||
}
|
||||
|
||||
interface MeshMessage {
|
||||
from: string
|
||||
to: string
|
||||
type: string
|
||||
payload: any
|
||||
timestamp: number
|
||||
signature?: string
|
||||
}
|
||||
|
||||
interface WorkflowResult {
|
||||
status: 'success' | 'failure'
|
||||
steps: WorkflowStepResult[]
|
||||
duration: number
|
||||
}
|
||||
```
|
||||
|
||||
## Package Exports
|
||||
|
||||
### @skillkit/core
|
||||
|
||||
```typescript
|
||||
export {
|
||||
// Discovery
|
||||
findAllSkills,
|
||||
findSkill,
|
||||
|
||||
// Quality
|
||||
evaluateSkillContent,
|
||||
getQualityGrade,
|
||||
|
||||
// Translation
|
||||
translateSkill,
|
||||
|
||||
// Memory
|
||||
MemoryCompressor,
|
||||
LearningStore,
|
||||
|
||||
// Recommendations
|
||||
RecommendationEngine,
|
||||
analyzeProject,
|
||||
|
||||
// Primer
|
||||
generateInstructions,
|
||||
|
||||
// Workflows
|
||||
WorkflowEngine,
|
||||
|
||||
// Testing
|
||||
SkillTestRunner,
|
||||
}
|
||||
```
|
||||
|
||||
### @skillkit/mesh
|
||||
|
||||
```typescript
|
||||
export {
|
||||
MeshHost,
|
||||
PeerIdentity,
|
||||
PeerRegistry,
|
||||
SecureTransport,
|
||||
}
|
||||
```
|
||||
|
||||
### @skillkit/messaging
|
||||
|
||||
```typescript
|
||||
export {
|
||||
MessagingClient,
|
||||
MessageBuilder,
|
||||
MessageRouter,
|
||||
}
|
||||
```
|
||||
|
||||
### @skillkit/memory
|
||||
|
||||
```typescript
|
||||
export {
|
||||
MemoryStore,
|
||||
TierManager,
|
||||
EmbeddingEncoder,
|
||||
}
|
||||
```
|
||||
|
||||
## Full Example: Custom Build Pipeline
|
||||
|
||||
```typescript
|
||||
import { promises as fs } from 'node:fs'
|
||||
import {
|
||||
analyzeProject,
|
||||
generateInstructions,
|
||||
RecommendationEngine,
|
||||
translateSkill,
|
||||
} from '@skillkit/core'
|
||||
|
||||
async function setupProject() {
|
||||
// 1. Analyze project
|
||||
const analysis = await analyzeProject('./my-project')
|
||||
|
||||
// 2. Generate base instructions
|
||||
const instructions = await generateInstructions(analysis, {
|
||||
agents: ['claude', 'cursor', 'windsurf'],
|
||||
})
|
||||
|
||||
// 3. Get recommendations
|
||||
const engine = new RecommendationEngine()
|
||||
const recommendations = engine.recommend(analysis)
|
||||
|
||||
// 4. Install top recommendations
|
||||
const topSkills = recommendations.slice(0, 5)
|
||||
for (const rec of topSkills) {
|
||||
console.log(`Installing ${rec.skill.name} (${rec.score}% match)`)
|
||||
}
|
||||
|
||||
// 5. Translate skills to all agents
|
||||
for (const agent of ['claude', 'cursor', 'windsurf']) {
|
||||
const translated = await translateSkill(
|
||||
topSkills[0].skill.content,
|
||||
agent
|
||||
)
|
||||
await fs.writeFile(`.${agent}/skills/${translated.filename}`, translated.content)
|
||||
}
|
||||
|
||||
console.log('✅ Project setup complete!')
|
||||
}
|
||||
|
||||
setupProject()
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Commands Reference](/docs/commands) - CLI commands
|
||||
- [Memory System](/docs/memory) - Persistent learning
|
||||
- [Mesh Network](/docs/mesh) - Multi-machine setup
|
||||
- [Workflows](/docs/workflows) - Automation
|
||||
- [Testing](/docs/testing) - Skill validation
|
||||
|
||||
@@ -233,10 +233,18 @@ skillkit init # Initialize project
|
||||
skillkit create <name> # Create new skill
|
||||
skillkit validate [path] # Validate skill format
|
||||
skillkit read <skills> # Read skill content
|
||||
skillkit publish # Publish to marketplace
|
||||
skillkit settings --set key=value # Configure settings
|
||||
```
|
||||
|
||||
## Publishing Commands
|
||||
|
||||
```bash
|
||||
skillkit publish [path] # Generate well-known hosting structure
|
||||
skillkit publish --output dir # Output to specific directory
|
||||
skillkit publish --dry-run # Preview without writing
|
||||
skillkit publish submit # Submit to SkillKit marketplace
|
||||
```
|
||||
|
||||
## Interactive TUI
|
||||
|
||||
```bash
|
||||
|
||||
@@ -86,19 +86,132 @@ skillkit settings --set autoSync=true
|
||||
skillkit settings --get agent
|
||||
```
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Memory System
|
||||
|
||||
```yaml
|
||||
# skillkit.yaml
|
||||
memory:
|
||||
enabled: true
|
||||
tier: personal # personal, project, global
|
||||
compression:
|
||||
minObservations: 10 # Compress after N observations
|
||||
autoExport: true # Auto-export as skills
|
||||
storage:
|
||||
backend: cozodb # cozodb, sqlite, memory
|
||||
path: ~/.skillkit/memory
|
||||
```
|
||||
|
||||
### Mesh Network
|
||||
|
||||
```yaml
|
||||
# skillkit.yaml
|
||||
mesh:
|
||||
enabled: true
|
||||
hostId: my-workstation
|
||||
discovery:
|
||||
method: local # local, tailscale, manual
|
||||
port: 9876
|
||||
security:
|
||||
mode: secure # development, signed, secure, strict
|
||||
keyPath: ~/.skillkit/mesh/keys
|
||||
peers:
|
||||
- id: laptop-dev
|
||||
address: 192.168.1.100
|
||||
trusted: true
|
||||
```
|
||||
|
||||
### Messaging
|
||||
|
||||
```yaml
|
||||
# skillkit.yaml
|
||||
messaging:
|
||||
enabled: true
|
||||
storagePath: ~/.skillkit/messages
|
||||
notifications: true
|
||||
autoArchive:
|
||||
enabled: true
|
||||
afterDays: 30
|
||||
```
|
||||
|
||||
### Primer
|
||||
|
||||
```yaml
|
||||
# skillkit.yaml
|
||||
primer:
|
||||
autoGenerate: true # Generate on changes
|
||||
agents:
|
||||
priority: [claude, cursor, windsurf]
|
||||
customize:
|
||||
tone: detailed # concise, detailed, technical
|
||||
includeExamples: true
|
||||
exclude:
|
||||
- node_modules
|
||||
- dist
|
||||
- .next
|
||||
```
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
~/.skillkit/
|
||||
├── preferences.json # User preferences
|
||||
├── cache/ # Marketplace cache
|
||||
└── memory/ # Learning storage
|
||||
├── observations/
|
||||
├── learnings/
|
||||
└── index.json
|
||||
├── memory/ # Learning storage
|
||||
│ ├── observations/
|
||||
│ ├── learnings/
|
||||
│ └── index.json
|
||||
├── mesh/ # Mesh network
|
||||
│ ├── keys/ # Encryption keys
|
||||
│ ├── peers.json # Known peers
|
||||
│ └── config.json
|
||||
└── messages/ # Inter-agent messages
|
||||
├── inbox/
|
||||
├── sent/
|
||||
└── archived/
|
||||
|
||||
./project/
|
||||
├── skillkit.yaml # Project config
|
||||
├── .skills # Team manifest
|
||||
└── skills/ # Local skills
|
||||
├── skills/ # Local skills
|
||||
└── .skillkit/ # Project-specific
|
||||
├── cache/
|
||||
├── primer-config.json
|
||||
└── memory/
|
||||
```
|
||||
|
||||
## Configuration Profiles
|
||||
|
||||
Create different profiles for different environments:
|
||||
|
||||
```yaml
|
||||
# skillkit.yaml
|
||||
profiles:
|
||||
development:
|
||||
agent: claude
|
||||
autoSync: true
|
||||
mesh:
|
||||
security:
|
||||
mode: development
|
||||
|
||||
production:
|
||||
agent: universal
|
||||
autoSync: false
|
||||
mesh:
|
||||
security:
|
||||
mode: strict
|
||||
```
|
||||
|
||||
Use profiles:
|
||||
|
||||
```bash
|
||||
skillkit --profile production sync
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Primer](/docs/primer) - Auto-generate instructions
|
||||
- [Memory System](/docs/memory) - Persistent learning
|
||||
- [Mesh Network](/docs/mesh) - Multi-machine setup
|
||||
- [Team Collaboration](/docs/teams) - Team configuration
|
||||
|
||||
@@ -7,7 +7,7 @@ description: Universal CLI for managing AI agent skills across 32 coding platfor
|
||||
|
||||
SkillKit is a universal command-line interface (CLI) and programmatic toolkit for managing AI agent skills across **32 AI coding platforms**.
|
||||
|
||||
**Current Version:** v1.7.5
|
||||
**Current Version:** v1.8.0
|
||||
|
||||
## The Problem
|
||||
|
||||
@@ -25,22 +25,80 @@ SkillKit provides a **"write once, deploy everywhere"** platform. Maintain a sin
|
||||
## Quick Install
|
||||
|
||||
```bash
|
||||
# Run instantly with npx (no install required)
|
||||
npx skillkit@latest
|
||||
|
||||
# Or install globally for frequent use
|
||||
npm install -g skillkit
|
||||
skillkit init
|
||||
skillkit install anthropics/skills
|
||||
skillkit sync
|
||||
```
|
||||
|
||||
## Key Features
|
||||
## Core Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Cross-Platform Translation** | Automatic conversion between 32 agent formats |
|
||||
| **Skill Discovery** | 15,000+ marketplace skills with AI recommendations |
|
||||
| **Smart Recommendations** | AI-powered skill suggestions based on your tech stack |
|
||||
| **Session Memory** | Persistent learning that survives across sessions |
|
||||
| **Primer** | Auto-generate agent instructions from your codebase |
|
||||
| **Mesh Network** | Multi-machine agent distribution with encrypted P2P |
|
||||
| **Inter-Agent Messaging** | Send messages between AI agents across your network |
|
||||
| **Team Collaboration** | Git-based `.skills` manifest for sharing |
|
||||
| **Quality Evaluation** | 0-100 scoring with A-F grades |
|
||||
| **Interactive TUI** | Beautiful terminal interface |
|
||||
| **Memory System** | Persistent learning across sessions |
|
||||
| **Workflow Orchestration** | Compose skills into multi-step automated workflows |
|
||||
| **Skill Testing** | Built-in test framework with assertions |
|
||||
| **CI/CD Integration** | GitHub Actions, GitLab CI, and pre-commit hooks |
|
||||
| **TypeScript API** | Full programmatic access to all features |
|
||||
| **Interactive TUI** | Beautiful terminal interface with real-time updates |
|
||||
|
||||
## Advanced Capabilities
|
||||
|
||||
### Session Memory System
|
||||
|
||||
Your AI agents learn patterns during sessions—then forget everything. SkillKit captures these learnings and makes them permanent.
|
||||
|
||||
```bash
|
||||
skillkit memory compress # Compress learnings
|
||||
skillkit memory search auth # Search knowledge
|
||||
skillkit memory export auth-patterns # Export as skill
|
||||
```
|
||||
|
||||
[Learn more →](/docs/memory)
|
||||
|
||||
### Primer - Auto-Generate Instructions
|
||||
|
||||
Automatically generate CLAUDE.md, .cursorrules, and agent instructions by analyzing your codebase.
|
||||
|
||||
```bash
|
||||
skillkit primer # Analyze project
|
||||
skillkit primer --all-agents # Generate for all 32 agents
|
||||
```
|
||||
|
||||
[Learn more →](/docs/primer)
|
||||
|
||||
### Mesh Network
|
||||
|
||||
Run agents across multiple machines with encrypted P2P communication.
|
||||
|
||||
```bash
|
||||
skillkit mesh init # Initialize mesh node
|
||||
skillkit mesh discover # Find peers on LAN
|
||||
skillkit mesh security init # Setup Ed25519 encryption
|
||||
```
|
||||
|
||||
[Learn more →](/docs/mesh)
|
||||
|
||||
### Inter-Agent Messaging
|
||||
|
||||
Send messages between AI agents across your mesh network.
|
||||
|
||||
```bash
|
||||
skillkit message send # Send to another agent
|
||||
skillkit message inbox # Check your inbox
|
||||
```
|
||||
|
||||
[Learn more →](/docs/messaging)
|
||||
|
||||
## Architecture
|
||||
|
||||
@@ -48,18 +106,23 @@ skillkit sync
|
||||
|------|------------|
|
||||
| **User Interfaces** | CLI (Clipanion v4), TUI (OpenTUI/React), Documentation |
|
||||
| **Business Logic** | @skillkit/core, @skillkit/agents (32 adapters) |
|
||||
| **Data Layer** | @skillkit/memory (CozoDB), @skillkit/mesh (WebSocket/UDP) |
|
||||
| **External Systems** | GitHub/GitLab, Marketplace (15,000+ skills) |
|
||||
|
||||
## Supported Agents
|
||||
## Supported Agents (32)
|
||||
|
||||
Claude Code, Cursor, Codex, Gemini CLI, OpenCode, GitHub Copilot, Windsurf, Antigravity, Amp, Clawdbot, Droid, Goose, Kilo Code, Kiro CLI, Roo Code, Trae, Cline, CodeBuddy, Continue, Crush, Factory, MCPJam, Mux, Neovate, OpenHands, Pi, Qoder, Qwen, Vercel, Zencoder, CommandCode, Universal
|
||||
|
||||
## Popular Sources
|
||||
[Full agent details →](/docs/agents)
|
||||
|
||||
## Popular Skill Sources
|
||||
|
||||
| Repository | Skills |
|
||||
|------------|--------|
|
||||
| anthropics/skills | PDF, XLSX, DOCX processing |
|
||||
| vercel-labs/agent-skills | React/Next.js best practices |
|
||||
| nextlevelbuilder/ui-ux-pro-max-skill | UI/UX design patterns |
|
||||
| superdesigndev/superdesign-skill | Modern design systems |
|
||||
|
||||
## Get Started
|
||||
|
||||
@@ -67,3 +130,19 @@ Claude Code, Cursor, Codex, Gemini CLI, OpenCode, GitHub Copilot, Windsurf, Anti
|
||||
2. [Quick Start](/docs/quickstart) - 5-minute guide
|
||||
3. [Commands](/docs/commands) - Full CLI reference
|
||||
4. [Skills](/docs/skills) - Skill format and lifecycle
|
||||
5. [API Reference](/docs/api-reference) - Programmatic access
|
||||
|
||||
## Use Cases
|
||||
|
||||
- **Multi-Agent Developer** - Write skills once, use across Claude, Cursor, Windsurf, and more
|
||||
- **Team Lead** - Share skills via Git-based manifest, ensure team alignment
|
||||
- **New Project Starter** - Auto-generate agent instructions with Primer
|
||||
- **Enterprise Architect** - Distribute agents across multiple machines with Mesh Network
|
||||
|
||||
## Enterprise Features
|
||||
|
||||
- **Private Registries** - Host internal skills in private repos
|
||||
- **Git-Based Sync** - Skills live in your repo, push to share
|
||||
- **CI/CD Integration** - Auto-validate and deploy skills on every commit
|
||||
- **TypeScript API** - Full programmatic access for custom workflows
|
||||
- **Security** - Ed25519 encryption, XChaCha20-Poly1305, TLS 1.3
|
||||
|
||||
@@ -48,8 +48,39 @@ skillkit install anthropics/skills --agent claude-code,cursor
|
||||
|
||||
## Publish Skills
|
||||
|
||||
### Self-Host on Your Domain (Recommended)
|
||||
|
||||
Generate a well-known URI structure (RFC 8615) to host skills on your own domain:
|
||||
|
||||
```bash
|
||||
# Create and validate your skill
|
||||
skillkit create my-skill
|
||||
skillkit validate my-skill
|
||||
skillkit publish
|
||||
|
||||
# Generate hosting structure
|
||||
skillkit publish ./my-skill --output ./public
|
||||
```
|
||||
|
||||
This creates:
|
||||
```
|
||||
.well-known/skills/
|
||||
index.json # Skill manifest for auto-discovery
|
||||
my-skill/
|
||||
SKILL.md # Your skill content
|
||||
```
|
||||
|
||||
Deploy the `.well-known` folder to your web server. Users can then install via:
|
||||
|
||||
```bash
|
||||
skillkit add https://your-domain.com
|
||||
```
|
||||
|
||||
### Submit to SkillKit Marketplace
|
||||
|
||||
To submit your skill for inclusion in the central marketplace:
|
||||
|
||||
```bash
|
||||
skillkit publish submit
|
||||
```
|
||||
|
||||
This opens a GitHub issue for review by maintainers.
|
||||
|
||||
@@ -9,14 +9,19 @@
|
||||
"agents",
|
||||
"translation",
|
||||
"marketplace",
|
||||
"tree",
|
||||
"recommendations",
|
||||
"primer",
|
||||
"memory",
|
||||
"mesh",
|
||||
"messaging",
|
||||
"workflows",
|
||||
"testing",
|
||||
"commands",
|
||||
"configuration",
|
||||
"api-reference",
|
||||
"cicd",
|
||||
"teams",
|
||||
"custom-agents",
|
||||
"contributing"
|
||||
]
|
||||
|
||||
@@ -0,0 +1,303 @@
|
||||
---
|
||||
title: Primer
|
||||
description: Auto-generate AI agent instructions from your codebase
|
||||
---
|
||||
|
||||
# Primer
|
||||
|
||||
Primer analyzes your codebase and automatically generates optimized instructions for all 32 AI agents. No more manual configuration—let SkillKit detect your tech stack, coding patterns, and project structure.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Analyze current project
|
||||
skillkit primer
|
||||
|
||||
# Generate for specific agents
|
||||
skillkit primer --agent claude,cursor,windsurf
|
||||
|
||||
# Generate for all 32 agents
|
||||
skillkit primer --all-agents
|
||||
|
||||
# Preview without writing files
|
||||
skillkit primer --dry-run
|
||||
```
|
||||
|
||||
## What Primer Detects
|
||||
|
||||
### Tech Stack
|
||||
- **Frameworks**: React, Next.js, Vue, Angular, Svelte, etc.
|
||||
- **Languages**: TypeScript, JavaScript, Python, Go, Rust, etc.
|
||||
- **Build Tools**: Vite, Webpack, Turbopack, esbuild
|
||||
- **Package Managers**: npm, pnpm, yarn, bun
|
||||
|
||||
### Project Patterns
|
||||
- **Architecture**: Monorepo, microservices, serverless
|
||||
- **Code Style**: Formatting rules, naming conventions
|
||||
- **Directory Structure**: Feature-based, layer-based, domain-driven
|
||||
- **Dependencies**: Key libraries and their versions
|
||||
|
||||
### Best Practices
|
||||
- **Testing Setup**: Jest, Vitest, Playwright, Cypress
|
||||
- **Linting**: ESLint, Prettier, TypeScript strict mode
|
||||
- **Documentation**: JSDoc, TSDoc, README patterns
|
||||
- **Git Workflow**: Branch strategy, commit conventions
|
||||
|
||||
## Generated Instructions
|
||||
|
||||
Primer creates agent-specific instructions for:
|
||||
|
||||
### Claude Code
|
||||
```
|
||||
.claude/
|
||||
└── CLAUDE.md # Full project context
|
||||
```
|
||||
|
||||
### Cursor
|
||||
```
|
||||
.cursor/
|
||||
└── .cursorrules # IDE-specific rules
|
||||
```
|
||||
|
||||
### GitHub Copilot
|
||||
```
|
||||
.github/
|
||||
└── copilot-instructions.md
|
||||
```
|
||||
|
||||
### All 32 Agents
|
||||
Each agent gets optimized instructions in their native format.
|
||||
|
||||
## Example Output
|
||||
|
||||
```bash
|
||||
$ skillkit primer
|
||||
|
||||
🔍 Analyzing project...
|
||||
|
||||
Detected:
|
||||
Framework: Next.js 14 (App Router)
|
||||
Language: TypeScript (strict mode)
|
||||
Styling: Tailwind CSS v3
|
||||
Testing: Vitest + Playwright
|
||||
Package Manager: pnpm
|
||||
|
||||
✅ Generated instructions for:
|
||||
- Claude Code (.claude/CLAUDE.md)
|
||||
- Cursor (.cursor/.cursorrules)
|
||||
- Codex (.codex/instructions.md)
|
||||
+ 29 more agents
|
||||
|
||||
💡 Tip: Run `skillkit sync` to apply changes
|
||||
```
|
||||
|
||||
## Customization
|
||||
|
||||
### Configuration File
|
||||
|
||||
Create `.skillkit/primer-config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"include": {
|
||||
"techStack": true,
|
||||
"codeStyle": true,
|
||||
"testingPatterns": true,
|
||||
"customRules": [
|
||||
"Always use async/await over promises",
|
||||
"Prefer functional components in React",
|
||||
"Use Zod for runtime validation"
|
||||
]
|
||||
},
|
||||
"exclude": {
|
||||
"directories": ["node_modules", "dist", ".next"],
|
||||
"patterns": ["*.test.ts", "*.spec.ts"]
|
||||
},
|
||||
"agents": {
|
||||
"priority": ["claude", "cursor", "windsurf"],
|
||||
"customize": {
|
||||
"claude": {
|
||||
"tone": "detailed",
|
||||
"examples": true
|
||||
},
|
||||
"cursor": {
|
||||
"tone": "concise",
|
||||
"shortcuts": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Template Overrides
|
||||
|
||||
Override default templates in `.skillkit/primer-templates/`:
|
||||
|
||||
```
|
||||
.skillkit/primer-templates/
|
||||
├── claude.template.md
|
||||
├── cursor.template.md
|
||||
└── shared/
|
||||
├── header.md
|
||||
└── footer.md
|
||||
```
|
||||
|
||||
## Update Strategies
|
||||
|
||||
### Incremental Updates
|
||||
|
||||
```bash
|
||||
# Update only when changes detected
|
||||
skillkit primer --incremental
|
||||
|
||||
# Force regeneration
|
||||
skillkit primer --force
|
||||
```
|
||||
|
||||
### Git Integration
|
||||
|
||||
```bash
|
||||
# Auto-generate on git hooks
|
||||
cat > .git/hooks/post-checkout << 'EOF'
|
||||
#!/usr/bin/env bash
|
||||
skillkit primer --incremental
|
||||
EOF
|
||||
chmod +x .git/hooks/post-checkout
|
||||
```
|
||||
|
||||
### CI/CD Pipeline
|
||||
|
||||
```yaml
|
||||
# .github/workflows/primer.yml
|
||||
name: Update Agent Instructions
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
paths:
|
||||
- 'package.json'
|
||||
- 'tsconfig.json'
|
||||
- 'src/**'
|
||||
|
||||
jobs:
|
||||
primer:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- run: npx skillkit primer --all-agents
|
||||
- uses: stefanzweifel/git-auto-commit-action@v4
|
||||
with:
|
||||
commit_message: "chore: update agent instructions"
|
||||
```
|
||||
|
||||
## Programmatic API
|
||||
|
||||
```typescript
|
||||
import { analyzeProject, generateInstructions } from '@skillkit/core';
|
||||
|
||||
// Analyze project
|
||||
const analysis = await analyzeProject('./my-project');
|
||||
console.log(analysis.techStack);
|
||||
// { framework: 'Next.js', language: 'TypeScript', ... }
|
||||
|
||||
// Generate instructions
|
||||
const instructions = await generateInstructions(analysis, {
|
||||
agents: ['claude', 'cursor'],
|
||||
includeExamples: true,
|
||||
tone: 'detailed',
|
||||
});
|
||||
|
||||
// Write to files
|
||||
for (const [agent, content] of Object.entries(instructions)) {
|
||||
await writeAgentFile(agent, content);
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### When to Run Primer
|
||||
|
||||
- **Initial Setup** - First time configuring agents
|
||||
- **Major Changes** - New frameworks or architecture changes
|
||||
- **Team Onboarding** - New developers joining the project
|
||||
- **Agent Migration** - Switching to new AI coding tools
|
||||
|
||||
### What to Commit
|
||||
|
||||
```text
|
||||
# Commit generated instructions
|
||||
.claude/
|
||||
.cursor/
|
||||
.github/copilot-instructions.md
|
||||
|
||||
# Don't commit
|
||||
.skillkit/cache/
|
||||
.skillkit/primer-temp/
|
||||
```
|
||||
|
||||
### Combining with Skills
|
||||
|
||||
Primer generates base instructions. Layer on specific skills:
|
||||
|
||||
```bash
|
||||
# 1. Generate base instructions
|
||||
skillkit primer --all-agents
|
||||
|
||||
# 2. Install domain-specific skills
|
||||
skillkit install anthropics/skills --skill pdf,xlsx
|
||||
|
||||
# 3. Sync everything
|
||||
skillkit sync
|
||||
```
|
||||
|
||||
## Comparison
|
||||
|
||||
| Method | Setup Time | Accuracy | Maintenance |
|
||||
|--------|-----------|----------|-------------|
|
||||
| **Manual Writing** | Hours | Variable | Manual updates |
|
||||
| **AI Generation** | Minutes | High | Auto-detect changes |
|
||||
| **Copy/Paste** | Minutes | Low | Stale quickly |
|
||||
| **Primer** | Seconds | Very High | Auto-incremental |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Primer Not Detecting Framework
|
||||
|
||||
```bash
|
||||
# Specify manually
|
||||
skillkit primer --framework nextjs --language typescript
|
||||
|
||||
# Check detection logs
|
||||
skillkit primer --verbose
|
||||
```
|
||||
|
||||
### Generated Instructions Too Generic
|
||||
|
||||
Customize with `primer-config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"tone": "detailed",
|
||||
"includeExamples": true,
|
||||
"customRules": [
|
||||
"Your specific coding guidelines..."
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Instructions Out of Sync
|
||||
|
||||
```bash
|
||||
# Force regeneration
|
||||
skillkit primer --force
|
||||
|
||||
# Clean cache
|
||||
rm -rf .skillkit/cache/primer
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Memory System](/docs/memory) - Capture learnings from sessions
|
||||
- [Skills](/docs/skills) - Install domain-specific skills
|
||||
- [Translation](/docs/translation) - Convert between agent formats
|
||||
- [Team Collaboration](/docs/teams) - Share instructions with your team
|
||||
@@ -136,6 +136,55 @@ skillkit install vercel-labs/agent-skills --agent claude,cursor,windsurf
|
||||
skillkit sync
|
||||
```
|
||||
|
||||
## 7. Advanced Features
|
||||
|
||||
### Auto-Generate Instructions (Primer)
|
||||
|
||||
Let SkillKit analyze your codebase and generate optimized instructions:
|
||||
|
||||
```bash
|
||||
skillkit primer # Analyze and generate
|
||||
skillkit primer --all-agents # Generate for all 32 agents
|
||||
```
|
||||
|
||||
[Learn more about Primer →](/docs/primer)
|
||||
|
||||
### Session Memory
|
||||
|
||||
Capture learnings from your AI sessions:
|
||||
|
||||
```bash
|
||||
skillkit memory compress # Compress learnings
|
||||
skillkit memory search auth # Search knowledge
|
||||
skillkit memory export auth-skill # Export as skill
|
||||
```
|
||||
|
||||
[Learn more about Memory →](/docs/memory)
|
||||
|
||||
### Mesh Network (Multi-Machine)
|
||||
|
||||
Distribute agents across multiple machines:
|
||||
|
||||
```bash
|
||||
skillkit mesh init # Initialize mesh node
|
||||
skillkit mesh discover # Find peers on LAN
|
||||
skillkit mesh security init # Setup encryption
|
||||
```
|
||||
|
||||
[Learn more about Mesh →](/docs/mesh)
|
||||
|
||||
### Inter-Agent Messaging
|
||||
|
||||
Send messages between AI agents:
|
||||
|
||||
```bash
|
||||
skillkit message send # Send to another agent
|
||||
skillkit message inbox # Check your inbox
|
||||
skillkit message reply <id> # Reply to message
|
||||
```
|
||||
|
||||
[Learn more about Messaging →](/docs/messaging)
|
||||
|
||||
## Team Collaboration
|
||||
|
||||
Share skills with your team using manifest files:
|
||||
@@ -154,6 +203,41 @@ skillkit manifest install
|
||||
|
||||
The `.skills` file can be committed to Git for team-wide consistency.
|
||||
|
||||
## Workflows & Automation
|
||||
|
||||
### Workflow Orchestration
|
||||
|
||||
Compose skills into multi-step workflows:
|
||||
|
||||
```bash
|
||||
skillkit workflow create feature-development
|
||||
skillkit workflow run feature-development
|
||||
```
|
||||
|
||||
[Learn more about Workflows →](/docs/workflows)
|
||||
|
||||
### Skill Testing
|
||||
|
||||
Test skills before deployment:
|
||||
|
||||
```bash
|
||||
skillkit test # Run all tests
|
||||
skillkit test --tags unit # Run specific tests
|
||||
```
|
||||
|
||||
[Learn more about Testing →](/docs/testing)
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
Generate GitHub Actions, GitLab CI configs:
|
||||
|
||||
```bash
|
||||
skillkit cicd init --provider github
|
||||
skillkit cicd init --provider gitlab
|
||||
```
|
||||
|
||||
[Learn more about CI/CD →](/docs/cicd)
|
||||
|
||||
## User Preferences
|
||||
|
||||
Your choices are saved to `~/.skillkit/preferences.json`:
|
||||
@@ -168,9 +252,44 @@ Your choices are saved to `~/.skillkit/preferences.json`:
|
||||
}
|
||||
```
|
||||
|
||||
## Complete Workflow Example
|
||||
|
||||
```bash
|
||||
# 1. Install SkillKit
|
||||
npm install -g skillkit
|
||||
|
||||
# 2. Initialize in your project
|
||||
cd my-project
|
||||
skillkit init
|
||||
|
||||
# 3. Auto-generate base instructions
|
||||
skillkit primer --all-agents
|
||||
|
||||
# 4. Get smart recommendations
|
||||
skillkit recommend
|
||||
|
||||
# 5. Install recommended skills
|
||||
skillkit install anthropics/skills
|
||||
|
||||
# 6. Setup mesh network (optional)
|
||||
skillkit mesh init
|
||||
|
||||
# 7. Setup session memory (optional)
|
||||
skillkit memory compress
|
||||
|
||||
# 8. Sync everything to agents
|
||||
skillkit sync
|
||||
|
||||
# 9. Launch TUI for visual management
|
||||
skillkit
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- **Browse Marketplace** - `skillkit marketplace`
|
||||
- **Create Custom Skills** - `skillkit create my-skill`
|
||||
- **Translate Between Agents** - `skillkit translate skill --to cursor`
|
||||
- **Auto-Generate Instructions** - `skillkit primer`
|
||||
- **Setup Memory System** - `skillkit memory compress`
|
||||
- **View All Commands** - `skillkit --help`
|
||||
- **API Reference** - [Programmatic Access →](/docs/api-reference)
|
||||
@@ -32,6 +32,33 @@ skillkit recommend --category security
|
||||
skillkit recommend --min-score 80
|
||||
```
|
||||
|
||||
## Explainable Recommendations
|
||||
|
||||
See WHY skills match your project:
|
||||
|
||||
```bash
|
||||
skillkit recommend --explain
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
vercel-react-best-practices (Score: 92)
|
||||
├── Matched: React, TypeScript, Next.js
|
||||
├── Your stack: Next.js 14, React 18
|
||||
└── Path: Frontend > React > Best Practices
|
||||
```
|
||||
|
||||
## LLM-Based Reasoning
|
||||
|
||||
Use reasoning-based discovery for complex queries:
|
||||
|
||||
```bash
|
||||
skillkit recommend --reasoning
|
||||
```
|
||||
|
||||
This uses an LLM to traverse the skill taxonomy and find the most relevant skills based on semantic understanding.
|
||||
|
||||
## How It Works
|
||||
|
||||
The engine analyzes:
|
||||
@@ -50,9 +77,22 @@ Scores based on:
|
||||
## Programmatic API
|
||||
|
||||
```typescript
|
||||
import { RecommendationEngine, analyzeProject } from '@skillkit/core'
|
||||
import {
|
||||
RecommendationEngine,
|
||||
ReasoningRecommendationEngine,
|
||||
analyzeProject
|
||||
} from '@skillkit/core'
|
||||
|
||||
// Basic recommendations
|
||||
const engine = new RecommendationEngine()
|
||||
const profile = await analyzeProject('./my-project')
|
||||
const recs = engine.recommend(profile)
|
||||
|
||||
// With reasoning and explanations
|
||||
const reasoningEngine = new ReasoningRecommendationEngine()
|
||||
await reasoningEngine.initReasoning()
|
||||
const explained = await reasoningEngine.recommendWithReasoning(profile, {
|
||||
reasoning: true,
|
||||
explain: true
|
||||
})
|
||||
```
|
||||
|
||||
@@ -94,6 +94,22 @@ Or manually create a `SKILL.md` file following the format above.
|
||||
# Test locally
|
||||
skillkit validate ./my-skill
|
||||
|
||||
# Publish to marketplace
|
||||
skillkit publish
|
||||
# Generate well-known hosting structure for self-hosting
|
||||
skillkit publish ./my-skill --output ./public
|
||||
|
||||
# Or submit to SkillKit marketplace
|
||||
skillkit publish submit
|
||||
```
|
||||
|
||||
### Self-Hosting
|
||||
|
||||
The `skillkit publish` command generates an RFC 8615 well-known URI structure:
|
||||
|
||||
```
|
||||
.well-known/skills/
|
||||
index.json # Manifest for auto-discovery
|
||||
my-skill/
|
||||
SKILL.md # Skill content
|
||||
```
|
||||
|
||||
Deploy to your domain and users can install via `skillkit add https://your-domain.com`.
|
||||
|
||||
@@ -0,0 +1,455 @@
|
||||
---
|
||||
title: Team Collaboration
|
||||
description: Share skills and maintain consistency across your development team
|
||||
---
|
||||
|
||||
# Team Collaboration
|
||||
|
||||
SkillKit provides powerful team collaboration features to ensure every developer has the same AI agent capabilities, follows the same patterns, and stays in sync.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Initialize team manifest
|
||||
skillkit team init
|
||||
|
||||
# Add skills to team manifest
|
||||
skillkit team add anthropics/skills
|
||||
skillkit team add ./local-skills
|
||||
|
||||
# Share with team (commit to Git)
|
||||
git add .skills
|
||||
git commit -m "Add team skills manifest"
|
||||
git push
|
||||
|
||||
# Team members install
|
||||
git pull
|
||||
skillkit team install
|
||||
```
|
||||
|
||||
## Team Manifest (.skills)
|
||||
|
||||
The `.skills` file is a Git-committable manifest that defines your team's skill stack.
|
||||
|
||||
### Example Manifest
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"name": "my-team",
|
||||
"skills": [
|
||||
{
|
||||
"source": "anthropics/skills",
|
||||
"skills": ["pdf", "xlsx", "docx"],
|
||||
"version": "1.2.0"
|
||||
},
|
||||
{
|
||||
"source": "vercel-labs/agent-skills",
|
||||
"skills": ["react-best-practices", "nextjs-patterns"],
|
||||
"version": "latest"
|
||||
},
|
||||
{
|
||||
"source": "./local-skills",
|
||||
"skills": ["company-coding-standards", "api-guidelines"],
|
||||
"type": "local"
|
||||
}
|
||||
],
|
||||
"agents": ["claude", "cursor", "windsurf"],
|
||||
"config": {
|
||||
"autoSync": true,
|
||||
"syncOnPull": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
### Initialize Team
|
||||
|
||||
```bash
|
||||
# Create .skills manifest
|
||||
skillkit team init
|
||||
|
||||
# Specify team name
|
||||
skillkit team init --name engineering-team
|
||||
|
||||
# Add initial skills
|
||||
skillkit team init --skills anthropics/skills,vercel-labs/agent-skills
|
||||
```
|
||||
|
||||
### Manage Skills
|
||||
|
||||
```bash
|
||||
# Add skill source
|
||||
skillkit team add anthropics/skills
|
||||
|
||||
# Add specific skills
|
||||
skillkit team add anthropics/skills --skills pdf,xlsx
|
||||
|
||||
# Remove skill
|
||||
skillkit team remove anthropics/skills
|
||||
|
||||
# List team skills
|
||||
skillkit team list
|
||||
```
|
||||
|
||||
### Install & Sync
|
||||
|
||||
```bash
|
||||
# Install all team skills
|
||||
skillkit team install
|
||||
|
||||
# Install and sync
|
||||
skillkit team install --sync
|
||||
|
||||
# Force reinstall
|
||||
skillkit team install --force
|
||||
```
|
||||
|
||||
### Share & Update
|
||||
|
||||
```bash
|
||||
# Share current skills as team manifest
|
||||
skillkit team share
|
||||
|
||||
# Update team manifest from installed skills
|
||||
skillkit team update
|
||||
|
||||
# Sync team manifest with Git remote
|
||||
skillkit team sync
|
||||
```
|
||||
|
||||
## Git Integration
|
||||
|
||||
### Auto-Install on Pull
|
||||
|
||||
Add to `.git/hooks/post-merge`:
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
if [ -f .skills ]; then
|
||||
echo "📦 Installing team skills..."
|
||||
skillkit team install --yes
|
||||
fi
|
||||
```
|
||||
|
||||
Make it executable:
|
||||
|
||||
```bash
|
||||
chmod +x .git/hooks/post-merge
|
||||
```
|
||||
|
||||
### Pre-Commit Validation
|
||||
|
||||
Ensure skills are valid before committing:
|
||||
|
||||
```bash
|
||||
# .git/hooks/pre-commit
|
||||
#!/bin/sh
|
||||
if [ -f .skills ]; then
|
||||
echo "🔍 Validating team skills..."
|
||||
skillkit team validate
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "❌ Team skills validation failed"
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
```
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
```yaml
|
||||
# .github/workflows/skills.yml
|
||||
name: Team Skills
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
- '.skills'
|
||||
|
||||
jobs:
|
||||
validate:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
|
||||
- name: Setup Node
|
||||
uses: actions/setup-node@v3
|
||||
with:
|
||||
node-version: '18'
|
||||
|
||||
- name: Install SkillKit
|
||||
run: npm install -g skillkit
|
||||
|
||||
- name: Validate Team Manifest
|
||||
run: skillkit team validate
|
||||
|
||||
- name: Install Skills
|
||||
run: skillkit team install --yes
|
||||
|
||||
- name: Run Skill Tests
|
||||
run: skillkit test
|
||||
```
|
||||
|
||||
### GitLab CI
|
||||
|
||||
```yaml
|
||||
# .gitlab-ci.yml
|
||||
skills:validate:
|
||||
stage: test
|
||||
script:
|
||||
- npm install -g skillkit
|
||||
- skillkit team validate
|
||||
- skillkit team install --yes
|
||||
- skillkit test
|
||||
only:
|
||||
changes:
|
||||
- .skills
|
||||
```
|
||||
|
||||
## Private Registries
|
||||
|
||||
Host proprietary skills in private repositories.
|
||||
|
||||
### Setup Private Registry
|
||||
|
||||
```bash
|
||||
# Add private registry
|
||||
skillkit registry add company-skills \
|
||||
--url https://github.com/mycompany/skills \
|
||||
--token $GITHUB_TOKEN
|
||||
|
||||
# Install from private registry
|
||||
skillkit install company-skills/auth-patterns
|
||||
```
|
||||
|
||||
### Team Manifest with Private Skills
|
||||
|
||||
```json
|
||||
{
|
||||
"skills": [
|
||||
{
|
||||
"source": "company-skills/proprietary-skills",
|
||||
"registry": "company-skills",
|
||||
"skills": ["auth-patterns", "payment-processing"],
|
||||
"private": true
|
||||
}
|
||||
],
|
||||
"registries": [
|
||||
{
|
||||
"name": "company-skills",
|
||||
"url": "https://github.com/mycompany/skills",
|
||||
"auth": "env:GITHUB_TOKEN"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Team Workflows
|
||||
|
||||
### Onboarding New Developers
|
||||
|
||||
```bash
|
||||
# 1. Clone repository
|
||||
git clone https://github.com/company/project
|
||||
cd project
|
||||
|
||||
# 2. Install team skills
|
||||
skillkit team install
|
||||
|
||||
# 3. Generate project instructions
|
||||
skillkit primer --all-agents
|
||||
|
||||
# 4. Sync to agents
|
||||
skillkit sync
|
||||
|
||||
# ✅ Developer is ready!
|
||||
```
|
||||
|
||||
### Creating Team-Wide Skills
|
||||
|
||||
```bash
|
||||
# 1. Create new skill
|
||||
skillkit create company-coding-standards
|
||||
|
||||
# 2. Add to local skills
|
||||
mv company-coding-standards ./local-skills/
|
||||
|
||||
# 3. Add to team manifest
|
||||
skillkit team add ./local-skills
|
||||
|
||||
# 4. Commit and push
|
||||
git add .skills local-skills/
|
||||
git commit -m "Add company coding standards"
|
||||
git push
|
||||
```
|
||||
|
||||
### Updating Team Skills
|
||||
|
||||
```bash
|
||||
# 1. Update skill version
|
||||
skillkit team update anthropics/skills --version 1.3.0
|
||||
|
||||
# 2. Test locally
|
||||
skillkit team install
|
||||
skillkit test
|
||||
|
||||
# 3. Commit if tests pass
|
||||
git add .skills
|
||||
git commit -m "Update anthropics/skills to v1.3.0"
|
||||
git push
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Version Pinning
|
||||
|
||||
Pin critical skills to specific versions:
|
||||
|
||||
```json
|
||||
{
|
||||
"skills": [
|
||||
{
|
||||
"source": "anthropics/skills",
|
||||
"version": "1.2.0",
|
||||
"pinned": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Skill Categories
|
||||
|
||||
Organize by category:
|
||||
|
||||
```json
|
||||
{
|
||||
"skills": [
|
||||
{
|
||||
"category": "core",
|
||||
"source": "anthropics/skills",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"category": "optional",
|
||||
"source": "vercel-labs/agent-skills",
|
||||
"required": false
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Environment-Specific Skills
|
||||
|
||||
```json
|
||||
{
|
||||
"environments": {
|
||||
"development": {
|
||||
"skills": ["debug-tools", "dev-server-patterns"]
|
||||
},
|
||||
"production": {
|
||||
"skills": ["performance-monitoring", "error-tracking"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Conflict Resolution
|
||||
|
||||
### Skill Name Conflicts
|
||||
|
||||
When multiple sources provide the same skill name:
|
||||
|
||||
```bash
|
||||
# List conflicts
|
||||
skillkit team conflicts
|
||||
|
||||
# Resolve by priority
|
||||
skillkit team resolve --priority "local,anthropics,vercel"
|
||||
```
|
||||
|
||||
### Version Conflicts
|
||||
|
||||
```bash
|
||||
# Show version mismatches
|
||||
skillkit team check-versions
|
||||
|
||||
# Align to latest
|
||||
skillkit team align --strategy latest
|
||||
|
||||
# Align to pinned
|
||||
skillkit team align --strategy pinned
|
||||
```
|
||||
|
||||
## Programmatic API
|
||||
|
||||
```typescript
|
||||
import { TeamManifest, TeamSync } from '@skillkit/core'
|
||||
|
||||
// Load team manifest
|
||||
const manifest = await TeamManifest.load('./.skills')
|
||||
|
||||
// Install team skills
|
||||
const sync = new TeamSync(manifest)
|
||||
await sync.install({
|
||||
agents: ['claude', 'cursor'],
|
||||
force: false,
|
||||
})
|
||||
|
||||
// Update manifest
|
||||
manifest.addSkill({
|
||||
source: 'anthropics/skills',
|
||||
skills: ['pdf'],
|
||||
version: '1.2.0',
|
||||
})
|
||||
|
||||
await manifest.save()
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Skills Not Syncing
|
||||
|
||||
```bash
|
||||
# Force reinstall
|
||||
skillkit team install --force
|
||||
|
||||
# Clear cache
|
||||
skillkit team clean
|
||||
|
||||
# Reinstall
|
||||
skillkit team install
|
||||
```
|
||||
|
||||
### Manifest Validation Errors
|
||||
|
||||
```bash
|
||||
# Validate manifest
|
||||
skillkit team validate --verbose
|
||||
|
||||
# Fix common issues
|
||||
skillkit team validate --fix
|
||||
```
|
||||
|
||||
### Merge Conflicts in .skills
|
||||
|
||||
```bash
|
||||
# Accept theirs
|
||||
git checkout --theirs .skills
|
||||
skillkit team install
|
||||
|
||||
# Accept ours
|
||||
git checkout --ours .skills
|
||||
skillkit team install
|
||||
|
||||
# Merge manually
|
||||
skillkit team merge-conflicts
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [CI/CD Integration](/docs/cicd) - Automate skill deployment
|
||||
- [Workflows](/docs/workflows) - Team-wide automation
|
||||
- [Testing](/docs/testing) - Validate skills before deployment
|
||||
@@ -0,0 +1,144 @@
|
||||
---
|
||||
title: Skill Tree
|
||||
description: Browse skills in a hierarchical taxonomy
|
||||
---
|
||||
|
||||
# Skill Tree
|
||||
|
||||
Browse and navigate skills organized in a hierarchical taxonomy structure.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Show full skill tree
|
||||
skillkit tree
|
||||
|
||||
# Navigate to a category
|
||||
skillkit tree Frontend
|
||||
|
||||
# Navigate to subcategory
|
||||
skillkit tree "Frontend > React"
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
### Display Tree
|
||||
|
||||
```bash
|
||||
skillkit tree # Full tree
|
||||
skillkit tree Development # Specific category
|
||||
skillkit tree --depth 2 # Limit display depth
|
||||
```
|
||||
|
||||
### Generate Tree
|
||||
|
||||
```bash
|
||||
skillkit tree --generate # Generate from skill index
|
||||
```
|
||||
|
||||
This builds a hierarchical tree from the skill index based on tags and metadata.
|
||||
|
||||
### Export Formats
|
||||
|
||||
```bash
|
||||
skillkit tree --json # JSON output
|
||||
skillkit tree --markdown # Markdown output
|
||||
```
|
||||
|
||||
### Statistics
|
||||
|
||||
```bash
|
||||
skillkit tree --stats
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
Overview:
|
||||
Total Skills: 15,064
|
||||
Categories: 156
|
||||
Max Depth: 4
|
||||
|
||||
Top-Level Categories:
|
||||
Development 4,521 skills (30.0%)
|
||||
Frontend (1,245), Backend (1,102), Mobile (456)
|
||||
DevOps 2,340 skills (15.5%)
|
||||
CI/CD (890), Kubernetes (567), Docker (445)
|
||||
AI/ML 1,890 skills (12.5%)
|
||||
LLM Integration (756), Agents (445), RAG (312)
|
||||
```
|
||||
|
||||
## Categories
|
||||
|
||||
The tree organizes skills into 12 top-level categories:
|
||||
|
||||
| Category | Description |
|
||||
|----------|-------------|
|
||||
| Development | General coding, programming patterns |
|
||||
| Frontend | React, Vue, Angular, Svelte, UI/UX |
|
||||
| Backend | Node.js, Python, Go, APIs, servers |
|
||||
| Mobile | React Native, Flutter, iOS, Android |
|
||||
| DevOps | CI/CD, Kubernetes, Docker, cloud |
|
||||
| Testing | Unit, E2E, integration, TDD |
|
||||
| Security | Auth, encryption, vulnerabilities |
|
||||
| AI/ML | LLM, agents, RAG, embeddings |
|
||||
| Database | SQL, NoSQL, ORM, migrations |
|
||||
| Tooling | Linting, formatting, bundling |
|
||||
| Documentation | API docs, guides, READMEs |
|
||||
| Performance | Optimization, caching, profiling |
|
||||
|
||||
## TUI Tree View
|
||||
|
||||
In the TUI, press `v` to toggle tree view in the Marketplace:
|
||||
|
||||
- **Arrow keys** - Navigate tree
|
||||
- **Enter** - Expand category / select skill
|
||||
- **←** - Go back / collapse
|
||||
- **v** - Toggle list/tree view
|
||||
|
||||
## Related Skills Graph
|
||||
|
||||
Find skills related to each other:
|
||||
|
||||
```typescript
|
||||
import { buildSkillGraph, getRelatedSkills } from '@skillkit/core'
|
||||
|
||||
const graph = buildSkillGraph(skills)
|
||||
const related = getRelatedSkills('react-patterns', graph, skills, {
|
||||
limit: 5,
|
||||
types: ['similar', 'complementary']
|
||||
})
|
||||
```
|
||||
|
||||
### Relation Types
|
||||
|
||||
- **similar** - Shares tags and functionality
|
||||
- **complementary** - Works well together
|
||||
- **dependency** - Required by other skills
|
||||
- **alternative** - Different approach to same problem
|
||||
|
||||
## Programmatic API
|
||||
|
||||
```typescript
|
||||
import {
|
||||
TreeGenerator,
|
||||
generateSkillTree,
|
||||
loadTree,
|
||||
saveTree,
|
||||
treeToMarkdown
|
||||
} from '@skillkit/core'
|
||||
|
||||
// Generate tree from skills
|
||||
const generator = new TreeGenerator({ maxDepth: 3 })
|
||||
const tree = generator.generateTree(skills)
|
||||
|
||||
// Or use the helper function
|
||||
const tree = generateSkillTree(skills)
|
||||
|
||||
// Save and load
|
||||
saveTree(tree, './skill-tree.json')
|
||||
const loaded = loadTree('./skill-tree.json')
|
||||
|
||||
// Export to markdown
|
||||
const markdown = treeToMarkdown(tree)
|
||||
```
|
||||
@@ -18,10 +18,12 @@ skillkit
|
||||
## Framework
|
||||
|
||||
Built on modern technologies:
|
||||
- **@opentui/react** - Terminal rendering
|
||||
- **React 19.0.0** - Component architecture
|
||||
- **@opentui/solid** - Terminal rendering with Solid.js
|
||||
- **Solid.js 1.9.0** - Reactive component architecture
|
||||
- **Bun 1.2.0+** - Runtime requirement
|
||||
|
||||
The TUI was migrated from React to Solid.js in v1.8.0 for improved performance and smaller bundle size.
|
||||
|
||||
## Screens
|
||||
|
||||
| Screen | Key | Purpose |
|
||||
@@ -103,6 +105,20 @@ Browse 15,000+ skills:
|
||||
- Featured skills
|
||||
- 3-phase animation loading
|
||||
- Quality scoring
|
||||
- **Tree View** - Press `v` to toggle hierarchical navigation
|
||||
|
||||
#### Tree View Mode
|
||||
|
||||
Navigate skills in a hierarchical taxonomy:
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `v` | Toggle tree/list view |
|
||||
| `→` or `Enter` | Expand category |
|
||||
| `←` | Collapse / go back |
|
||||
| `↑`/`↓` | Navigate |
|
||||
|
||||
Categories include: Development, Frontend, Backend, Mobile, DevOps, Testing, Security, AI/ML, Database, Tooling, Documentation, Performance
|
||||
|
||||
### Recommend Screen
|
||||
|
||||
@@ -159,8 +175,10 @@ loadSkills()
|
||||
|
||||
### Performance Optimizations
|
||||
|
||||
- `useMemo` for filtered lists
|
||||
- `useCallback` for event handlers
|
||||
- `createMemo` for filtered lists and computed values
|
||||
- `createSignal` for reactive state management
|
||||
- `createEffect` for side effects and subscriptions
|
||||
- Windowed list rendering for large datasets
|
||||
- Pagination limits rendered items
|
||||
- Progressive animation with phases
|
||||
|
||||
@@ -174,18 +192,32 @@ loadSkills()
|
||||
|
||||
## Integration
|
||||
|
||||
The TUI integrates with @skillkit/core:
|
||||
The TUI integrates with @skillkit/core using Solid.js reactive patterns:
|
||||
|
||||
```typescript
|
||||
findAllSkills(searchDirs) // Returns skill metadata
|
||||
evaluateSkillDirectory(path) // Quality metrics
|
||||
getQualityGrade(score) // 0-100 to A-F
|
||||
import { createSignal, createMemo, createEffect } from 'solid-js';
|
||||
|
||||
const [skills, setSkills] = createSignal([]);
|
||||
|
||||
createEffect(async () => {
|
||||
const result = await findAllSkills(searchDirs);
|
||||
setSkills(result);
|
||||
});
|
||||
|
||||
const filteredSkills = createMemo(() =>
|
||||
skills().filter(s => s.name.includes(searchTerm()))
|
||||
);
|
||||
```
|
||||
|
||||
Core functions:
|
||||
- `findAllSkills(searchDirs)` - Returns skill metadata
|
||||
- `evaluateSkillDirectory(path)` - Quality metrics
|
||||
- `getQualityGrade(score)` - 0-100 to A-F
|
||||
|
||||
## Graceful Exit
|
||||
|
||||
The TUI handles shutdown gracefully:
|
||||
1. Unmounts React components
|
||||
1. Runs Solid.js cleanup functions (`onCleanup`)
|
||||
2. Restores terminal state
|
||||
3. Cleans up signal handlers
|
||||
4. Exits process cleanly
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "skillkit-docs",
|
||||
"version": "1.8.0",
|
||||
"version": "1.10.0",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"build": "next build",
|
||||
|
||||
@@ -1,17 +1,5 @@
|
||||
import Link from 'next/link'
|
||||
|
||||
const GITHUB_ICON = (
|
||||
<svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
|
||||
<path fillRule="evenodd" d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.531 1.032 1.531 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0112 6.844c.85.004 1.705.115 2.504.337 1.909-1.296 2.747-1.027 2.747-1.027.546 1.379.202 2.398.1 2.651.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.019 10.019 0 0022 12.017C22 6.484 17.522 2 12 2z" clipRule="evenodd" />
|
||||
</svg>
|
||||
)
|
||||
|
||||
const NPM_ICON = (
|
||||
<svg className="w-5 h-5" viewBox="0 0 24 24" fill="currentColor">
|
||||
<path d="M0 7.334v8h6.666v1.332H12v-1.332h12v-8H0zm6.666 6.664H5.334v-4H3.999v4H1.335V8.667h5.331v5.331zm4 0v1.336H8.001V8.667h5.334v5.332h-2.669v-.001zm12.001 0h-1.33v-4h-1.336v4h-1.335v-4h-1.33v4h-2.671V8.667h8.002v5.331zM10.665 10H12v2.667h-1.335V10z" />
|
||||
</svg>
|
||||
)
|
||||
|
||||
export default function HomeLayout({
|
||||
children,
|
||||
}: {
|
||||
@@ -22,34 +10,24 @@ export default function HomeLayout({
|
||||
<nav className="fixed top-0 left-0 right-0 z-50 border-b border-zinc-800 bg-black/90 backdrop-blur-md">
|
||||
<div className="mx-auto max-w-5xl px-4 sm:px-6 lg:px-8">
|
||||
<div className="flex h-14 items-center justify-between">
|
||||
<Link href="/" className="flex items-center gap-2 cursor-pointer">
|
||||
<Link href="/" className="flex items-center gap-2">
|
||||
<div className="w-4 h-4 bg-white"></div>
|
||||
<span className="text-base font-bold tracking-tight text-white font-mono">SKILLKIT</span>
|
||||
</Link>
|
||||
<div className="flex items-center gap-2 sm:gap-4">
|
||||
<div className="flex items-center gap-4">
|
||||
<Link
|
||||
href="/docs"
|
||||
className="text-zinc-400 hover:text-white transition-colors text-sm font-mono"
|
||||
>
|
||||
Docs
|
||||
</Link>
|
||||
<a
|
||||
href="https://www.npmjs.com/package/skillkit"
|
||||
target="_blank"
|
||||
rel="noreferrer noopener"
|
||||
className="text-zinc-400 hover:text-red-500 transition-colors p-2"
|
||||
aria-label="npm"
|
||||
>
|
||||
{NPM_ICON}
|
||||
</a>
|
||||
<a
|
||||
href="https://github.com/rohitg00/skillkit"
|
||||
target="_blank"
|
||||
rel="noreferrer noopener"
|
||||
className="text-zinc-400 hover:text-white transition-colors p-2"
|
||||
aria-label="GitHub"
|
||||
rel="noopener noreferrer"
|
||||
className="text-zinc-400 hover:text-white transition-colors text-sm font-mono"
|
||||
>
|
||||
{GITHUB_ICON}
|
||||
GitHub
|
||||
</a>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
@@ -1,40 +1,96 @@
|
||||
'use client'
|
||||
|
||||
import { Hero } from '@/components/Hero'
|
||||
import { Agents } from '@/components/Agents'
|
||||
import { Features } from '@/components/Features'
|
||||
import { Commands } from '@/components/Commands'
|
||||
import { SkillGenerator } from '@/components/SkillGenerator'
|
||||
import { SkillSubmitForm } from '@/components/SkillSubmitForm'
|
||||
import { Footer } from '@/components/Footer'
|
||||
import Link from 'next/link'
|
||||
|
||||
export default function HomePage() {
|
||||
return (
|
||||
<div className="min-h-screen bg-black text-zinc-100 font-sans selection:bg-white selection:text-black">
|
||||
<main>
|
||||
<Hero />
|
||||
<Agents />
|
||||
<Features />
|
||||
<Commands />
|
||||
|
||||
<section id="skills" className="py-12 border-b border-zinc-800">
|
||||
<SkillGenerator />
|
||||
</section>
|
||||
|
||||
<section id="submit" className="py-12 border-b border-zinc-800 bg-zinc-900/50">
|
||||
<div className="mx-auto max-w-5xl px-4 sm:px-6 lg:px-8">
|
||||
<div className="text-center mb-8">
|
||||
<h2 className="text-2xl font-bold text-white mb-2 font-mono">Submit Your Skill</h2>
|
||||
<p className="text-zinc-400 font-mono text-sm">
|
||||
Share your AI agent skills with the community.
|
||||
</p>
|
||||
</div>
|
||||
<SkillSubmitForm />
|
||||
<div className="min-h-screen bg-black text-zinc-100">
|
||||
<main className="mx-auto max-w-5xl px-4 sm:px-6 lg:px-8 py-20">
|
||||
{/* Hero */}
|
||||
<div className="text-center mb-16">
|
||||
<div className="inline-flex items-center space-x-2 border border-zinc-800 bg-zinc-900/50 px-3 py-1 mb-6">
|
||||
<span className="flex h-2 w-2 bg-white rounded-full"></span>
|
||||
<span className="text-sm font-mono text-zinc-400">v1.8.0</span>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<h1 className="text-4xl sm:text-5xl lg:text-6xl font-bold tracking-tight text-white mb-6 font-mono">
|
||||
Universal Skills for<br />
|
||||
<span className="text-zinc-500">AI Coding Agents</span>
|
||||
</h1>
|
||||
|
||||
<p className="text-lg text-zinc-400 mb-8 max-w-2xl mx-auto font-mono">
|
||||
One CLI to install, sync, and manage skills across Claude Code, Cursor,
|
||||
Windsurf, Copilot, and 28 more agents. 15,000+ skills ready to use.
|
||||
</p>
|
||||
|
||||
<div className="flex flex-wrap justify-center gap-4 mb-12">
|
||||
<code className="inline-flex items-center bg-zinc-900 border border-zinc-700 px-4 py-3 text-sm font-mono">
|
||||
<span className="text-zinc-500 mr-2">$</span>
|
||||
<span className="text-white">npx skillkit@latest</span>
|
||||
</code>
|
||||
|
||||
<Link
|
||||
href="/docs"
|
||||
className="inline-flex items-center bg-white text-black px-6 py-3 font-mono text-sm hover:bg-zinc-200 transition-colors"
|
||||
>
|
||||
Read the Docs →
|
||||
</Link>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{/* Features Grid */}
|
||||
<div className="grid grid-cols-1 md:grid-cols-3 gap-6 mb-16">
|
||||
<div className="border border-zinc-800 bg-zinc-900/30 p-6">
|
||||
<h3 className="text-lg font-bold text-white mb-2 font-mono">32 Agents</h3>
|
||||
<p className="text-zinc-500 text-sm">Claude, Cursor, Codex, Windsurf, Copilot, and 27 more supported out of the box.</p>
|
||||
</div>
|
||||
<div className="border border-zinc-800 bg-zinc-900/30 p-6">
|
||||
<h3 className="text-lg font-bold text-white mb-2 font-mono">15,000+ Skills</h3>
|
||||
<p className="text-zinc-500 text-sm">Browse the marketplace or create your own. Install with a single command.</p>
|
||||
</div>
|
||||
<div className="border border-zinc-800 bg-zinc-900/30 p-6">
|
||||
<h3 className="text-lg font-bold text-white mb-2 font-mono">Auto Translation</h3>
|
||||
<p className="text-zinc-500 text-sm">Write once, deploy everywhere. Automatic format conversion between all agents.</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{/* Quick Links */}
|
||||
<div className="text-center">
|
||||
<h2 className="text-2xl font-bold text-white mb-6 font-mono">Get Started</h2>
|
||||
<div className="flex flex-wrap justify-center gap-4">
|
||||
<Link href="/docs/quickstart" className="text-zinc-400 hover:text-white font-mono text-sm border border-zinc-800 px-4 py-2 hover:border-zinc-600 transition-colors">
|
||||
Quick Start
|
||||
</Link>
|
||||
<Link href="/docs/primer" className="text-zinc-400 hover:text-white font-mono text-sm border border-zinc-800 px-4 py-2 hover:border-zinc-600 transition-colors">
|
||||
Primer
|
||||
</Link>
|
||||
<Link href="/docs/memory" className="text-zinc-400 hover:text-white font-mono text-sm border border-zinc-800 px-4 py-2 hover:border-zinc-600 transition-colors">
|
||||
Memory System
|
||||
</Link>
|
||||
<Link href="/docs/mesh" className="text-zinc-400 hover:text-white font-mono text-sm border border-zinc-800 px-4 py-2 hover:border-zinc-600 transition-colors">
|
||||
Mesh Network
|
||||
</Link>
|
||||
<Link href="/docs/api-reference" className="text-zinc-400 hover:text-white font-mono text-sm border border-zinc-800 px-4 py-2 hover:border-zinc-600 transition-colors">
|
||||
API Reference
|
||||
</Link>
|
||||
</div>
|
||||
</div>
|
||||
</main>
|
||||
|
||||
<Footer />
|
||||
|
||||
{/* Footer */}
|
||||
<footer className="border-t border-zinc-800 py-8">
|
||||
<div className="mx-auto max-w-5xl px-4 sm:px-6 lg:px-8">
|
||||
<div className="flex flex-col sm:flex-row items-center justify-between gap-4">
|
||||
<div className="flex items-center gap-2">
|
||||
<div className="w-4 h-4 bg-white"></div>
|
||||
<span className="font-mono font-bold text-white">SKILLKIT</span>
|
||||
</div>
|
||||
<div className="flex items-center gap-6 text-sm font-mono text-zinc-500">
|
||||
<a href="https://github.com/rohitg00/skillkit" target="_blank" rel="noopener noreferrer" className="hover:text-white transition-colors">GitHub</a>
|
||||
<a href="https://www.npmjs.com/package/skillkit" target="_blank" rel="noopener noreferrer" className="hover:text-white transition-colors">npm</a>
|
||||
<Link href="/docs" className="hover:text-white transition-colors">Docs</Link>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</footer>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
+66
-34
@@ -9,6 +9,10 @@ import { Commands } from './components/Commands';
|
||||
import { StackBuilder } from './components/StackBuilder';
|
||||
import { TrendingSkills } from './components/TrendingSkills';
|
||||
import { Attribution } from './components/Attribution';
|
||||
import { AdvancedFeatures } from './components/AdvancedFeatures';
|
||||
import { UseCases } from './components/UseCases';
|
||||
import { TeamEnterprise } from './components/TeamEnterprise';
|
||||
import { useStats } from './hooks/useStats';
|
||||
|
||||
const GITHUB_ICON = (
|
||||
<svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
|
||||
@@ -16,12 +20,6 @@ const GITHUB_ICON = (
|
||||
</svg>
|
||||
);
|
||||
|
||||
const NPM_ICON = (
|
||||
<svg className="w-5 h-5" viewBox="0 0 24 24" fill="currentColor">
|
||||
<path d="M0 7.334v8h6.666v1.332H12v-1.332h12v-8H0zm6.666 6.664H5.334v-4H3.999v4H1.335V8.667h5.331v5.331zm4 0v1.336H8.001V8.667h5.334v5.332h-2.669v-.001zm12.001 0h-1.33v-4h-1.336v4h-1.335v-4h-1.33v4h-2.671V8.667h8.002v5.331zM10.665 10H12v2.667h-1.335V10z" />
|
||||
</svg>
|
||||
);
|
||||
|
||||
function scrollToTop(e: React.MouseEvent): void {
|
||||
e.preventDefault();
|
||||
window.scrollTo({ top: 0, behavior: 'smooth' });
|
||||
@@ -37,6 +35,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)' }}>
|
||||
@@ -47,13 +47,6 @@ export default function App(): React.ReactElement {
|
||||
<span className="text-base font-bold tracking-tight text-white font-mono">SKILLKIT</span>
|
||||
</a>
|
||||
<div className="hidden sm:flex items-center gap-4 text-xs font-mono">
|
||||
<a
|
||||
href="#stack"
|
||||
onClick={(e) => scrollToSection(e, 'stack')}
|
||||
className="text-zinc-500 hover:text-white transition-colors"
|
||||
>
|
||||
Stack
|
||||
</a>
|
||||
<a
|
||||
href="#trending"
|
||||
onClick={(e) => scrollToSection(e, 'trending')}
|
||||
@@ -61,25 +54,39 @@ export default function App(): React.ReactElement {
|
||||
>
|
||||
Trending
|
||||
</a>
|
||||
<a
|
||||
href="#stack"
|
||||
onClick={(e) => scrollToSection(e, 'stack')}
|
||||
className="text-zinc-500 hover:text-white transition-colors"
|
||||
>
|
||||
Stack
|
||||
</a>
|
||||
<a
|
||||
href="#advanced"
|
||||
onClick={(e) => scrollToSection(e, 'advanced')}
|
||||
className="text-zinc-500 hover:text-white transition-colors"
|
||||
>
|
||||
Features
|
||||
</a>
|
||||
<a
|
||||
href="#use-cases"
|
||||
onClick={(e) => scrollToSection(e, 'use-cases')}
|
||||
className="text-zinc-500 hover:text-white transition-colors"
|
||||
>
|
||||
Use Cases
|
||||
</a>
|
||||
<a
|
||||
href="#skills"
|
||||
onClick={(e) => scrollToSection(e, 'skills')}
|
||||
className="text-zinc-500 hover:text-white transition-colors"
|
||||
>
|
||||
Find Skills
|
||||
</a>
|
||||
<a
|
||||
href="#sources"
|
||||
onClick={(e) => scrollToSection(e, 'sources')}
|
||||
className="text-zinc-500 hover:text-white transition-colors"
|
||||
>
|
||||
Sources
|
||||
Generator
|
||||
</a>
|
||||
</div>
|
||||
<div className="flex items-center gap-3 sm:gap-4">
|
||||
<a
|
||||
href="https://agenstskills.com/docs"
|
||||
className="text-zinc-400 hover:text-white transition-colors text-sm font-mono hidden sm:block"
|
||||
className="text-zinc-400 hover:text-white transition-colors text-xs sm:text-sm font-mono"
|
||||
>
|
||||
Docs
|
||||
</a>
|
||||
@@ -98,11 +105,11 @@ 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">
|
||||
<div className="flex items-center justify-center gap-6 text-xs font-mono">
|
||||
<div className="flex items-center justify-center gap-4 sm:gap-6 text-xs font-mono">
|
||||
<a
|
||||
href="https://www.npmjs.com/package/skillkit"
|
||||
target="_blank"
|
||||
@@ -110,7 +117,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
|
||||
@@ -122,7 +129,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
|
||||
@@ -134,14 +141,14 @@ 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">·</span>
|
||||
<span className="text-zinc-800 hidden sm:inline">·</span>
|
||||
<a
|
||||
href="https://github.com/rohitg00/skillkit/blob/main/LICENSE"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
className="text-zinc-500 hover:text-white transition-colors"
|
||||
className="text-zinc-500 hover:text-white transition-colors hidden sm:inline"
|
||||
>
|
||||
Apache 2.0
|
||||
</a>
|
||||
@@ -149,22 +156,46 @@ export default function App(): React.ReactElement {
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{/* Agent Support - Quick visual proof */}
|
||||
<Agents />
|
||||
|
||||
{/* Core Features & Comparison - Value prop at a glance */}
|
||||
<Features />
|
||||
<Commands />
|
||||
|
||||
<section id="stack" style={{ scrollMarginTop: '4rem' }}>
|
||||
<StackBuilder />
|
||||
</section>
|
||||
|
||||
{/* Trending Skills - Social proof, what's popular */}
|
||||
<section id="trending" style={{ scrollMarginTop: '4rem' }}>
|
||||
<TrendingSkills />
|
||||
</section>
|
||||
|
||||
{/* Stack Builder - Interactive, engaging */}
|
||||
<section id="stack" style={{ scrollMarginTop: '4rem' }}>
|
||||
<StackBuilder />
|
||||
</section>
|
||||
|
||||
{/* Advanced Capabilities: Memory, Primer, Mesh, Messaging */}
|
||||
<section id="advanced" style={{ scrollMarginTop: '4rem' }}>
|
||||
<AdvancedFeatures />
|
||||
</section>
|
||||
|
||||
{/* Commands Reference */}
|
||||
<Commands />
|
||||
|
||||
{/* Real-World Use Cases */}
|
||||
<section id="use-cases" style={{ scrollMarginTop: '4rem' }}>
|
||||
<UseCases />
|
||||
</section>
|
||||
|
||||
{/* Team & Enterprise */}
|
||||
<section id="team" style={{ scrollMarginTop: '4rem' }}>
|
||||
<TeamEnterprise />
|
||||
</section>
|
||||
|
||||
{/* Skill Generator */}
|
||||
<section id="skills" className="py-12 border-b border-zinc-800" style={{ scrollMarginTop: '4rem' }}>
|
||||
<SkillGenerator />
|
||||
</section>
|
||||
|
||||
{/* Submit Skill */}
|
||||
<section id="submit" className="py-12 border-b border-zinc-800" style={{ backgroundColor: '#09090b', scrollMarginTop: '4rem' }}>
|
||||
<div className="mx-auto max-w-5xl px-4 sm:px-6 lg:px-8">
|
||||
<div className="text-center mb-8">
|
||||
@@ -177,6 +208,7 @@ export default function App(): React.ReactElement {
|
||||
</div>
|
||||
</section>
|
||||
|
||||
{/* Attribution & Sources */}
|
||||
<section id="sources" style={{ scrollMarginTop: '4rem' }}>
|
||||
<Attribution />
|
||||
</section>
|
||||
|
||||
@@ -0,0 +1,212 @@
|
||||
import React, { useState } from 'react';
|
||||
|
||||
interface AdvancedFeature {
|
||||
id: string;
|
||||
title: string;
|
||||
subtitle: string;
|
||||
description: string;
|
||||
icon: React.ReactNode;
|
||||
commands: Array<{ cmd: string; desc: string }>;
|
||||
highlight: string;
|
||||
}
|
||||
|
||||
const ADVANCED_FEATURES: AdvancedFeature[] = [
|
||||
{
|
||||
id: 'memory',
|
||||
title: 'Session Memory',
|
||||
subtitle: 'AI That Actually Learns',
|
||||
description: 'Your AI agents learn patterns during sessions—then forget everything. SkillKit captures these learnings and makes them permanent. Knowledge persists across sessions, projects, and even different agents.',
|
||||
highlight: 'Persistent learning across all agents',
|
||||
icon: (
|
||||
<svg className="w-8 h-8" 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" />
|
||||
</svg>
|
||||
),
|
||||
commands: [
|
||||
{ cmd: 'memory compress', desc: 'Turn observations into learnings' },
|
||||
{ cmd: 'memory search "auth"', desc: 'Find past patterns' },
|
||||
{ cmd: 'memory export', desc: 'Convert to shareable skill' },
|
||||
{ cmd: 'memory --global', desc: 'Share across all projects' },
|
||||
],
|
||||
},
|
||||
{
|
||||
id: 'primer',
|
||||
title: 'Primer',
|
||||
subtitle: 'Zero-Config AI Instructions',
|
||||
description: 'Automatically generate CLAUDE.md, .cursorrules, and agent instructions by analyzing your codebase. Detects your tech stack, coding patterns, and project structure—then creates optimized instructions for all 32 agents.',
|
||||
highlight: 'Auto-generates instructions for 32 agents',
|
||||
icon: (
|
||||
<svg className="w-8 h-8" fill="none" viewBox="0 0 24 24" stroke="currentColor">
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2m-3 7h3m-3 4h3m-6-4h.01M9 16h.01" />
|
||||
</svg>
|
||||
),
|
||||
commands: [
|
||||
{ cmd: 'primer', desc: 'Analyze & generate for detected agents' },
|
||||
{ cmd: 'primer --all-agents', desc: 'Generate for all 32 agents' },
|
||||
{ cmd: 'primer --analyze-only', desc: 'Preview codebase analysis' },
|
||||
{ cmd: 'primer --json', desc: 'Machine-readable output' },
|
||||
],
|
||||
},
|
||||
{
|
||||
id: 'mesh',
|
||||
title: 'Mesh Network',
|
||||
subtitle: 'Multi-Machine Agent Distribution',
|
||||
description: 'Run agents across multiple machines with encrypted P2P communication. Discover peers on your LAN, establish trust with Ed25519 keys, and distribute skills across your entire infrastructure.',
|
||||
highlight: 'Encrypted P2P agent network',
|
||||
icon: (
|
||||
<svg className="w-8 h-8" fill="none" viewBox="0 0 24 24" stroke="currentColor">
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M21 12a9 9 0 01-9 9m9-9a9 9 0 00-9-9m9 9H3m9 9a9 9 0 01-9-9m9 9c1.657 0 3-4.03 3-9s-1.343-9-3-9m0 18c-1.657 0-3-4.03-3-9s1.343-9 3-9m-9 9a9 9 0 019-9" />
|
||||
</svg>
|
||||
),
|
||||
commands: [
|
||||
{ cmd: 'mesh init', desc: 'Initialize your mesh node' },
|
||||
{ cmd: 'mesh discover', desc: 'Find peers on LAN' },
|
||||
{ cmd: 'mesh security init', desc: 'Setup Ed25519 encryption' },
|
||||
{ cmd: 'mesh peer trust <id>', desc: 'Establish peer trust' },
|
||||
],
|
||||
},
|
||||
{
|
||||
id: 'messaging',
|
||||
title: 'Inter-Agent Messaging',
|
||||
subtitle: 'Agents That Communicate',
|
||||
description: 'Send messages between AI agents across your mesh network. Coordinate complex tasks, share context, and build multi-agent workflows where agents collaborate to solve problems.',
|
||||
highlight: 'Agents collaborate across machines',
|
||||
icon: (
|
||||
<svg className="w-8 h-8" fill="none" viewBox="0 0 24 24" stroke="currentColor">
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M8 12h.01M12 12h.01M16 12h.01M21 12c0 4.418-4.03 8-9 8a9.863 9.863 0 01-4.255-.949L3 20l1.395-3.72C3.512 15.042 3 13.574 3 12c0-4.418 4.03-8 9-8s9 3.582 9 8z" />
|
||||
</svg>
|
||||
),
|
||||
commands: [
|
||||
{ cmd: 'message send', desc: 'Send to another agent' },
|
||||
{ cmd: 'message inbox', desc: 'Check your inbox' },
|
||||
{ cmd: 'message reply <id>', desc: 'Reply to messages' },
|
||||
{ cmd: 'message archive', desc: 'Archive old messages' },
|
||||
],
|
||||
},
|
||||
];
|
||||
|
||||
export function AdvancedFeatures(): React.ReactElement {
|
||||
const [activeFeature, setActiveFeature] = useState<string>('memory');
|
||||
const feature = ADVANCED_FEATURES.find(f => f.id === activeFeature) || ADVANCED_FEATURES[0];
|
||||
|
||||
return (
|
||||
<section className="py-12 sm:py-16 border-b border-zinc-800 relative overflow-hidden">
|
||||
{/* Gradient background */}
|
||||
<div className="absolute inset-0 bg-gradient-to-b from-zinc-950 via-zinc-900/50 to-zinc-950"></div>
|
||||
<div className="absolute inset-0 bg-[radial-gradient(ellipse_at_top,rgba(255,255,255,0.03),transparent_50%)]"></div>
|
||||
|
||||
<div className="mx-auto max-w-5xl px-4 sm:px-6 lg:px-8 relative">
|
||||
{/* Section Header */}
|
||||
<div className="text-center mb-8 sm:mb-12">
|
||||
<div className="inline-flex items-center gap-2 border border-zinc-700 bg-zinc-900/80 px-2 sm:px-3 py-1 mb-4 backdrop-blur-sm">
|
||||
<span className="w-1.5 h-1.5 bg-emerald-400 rounded-full animate-pulse"></span>
|
||||
<span className="text-[10px] sm:text-xs font-mono text-zinc-300 uppercase tracking-wider">Beyond Installation</span>
|
||||
</div>
|
||||
<h2 className="text-2xl sm:text-3xl lg:text-4xl font-bold text-white mb-3 font-mono tracking-tight">
|
||||
Advanced Capabilities
|
||||
</h2>
|
||||
<p className="text-zinc-400 font-mono text-xs sm:text-sm max-w-2xl mx-auto px-4">
|
||||
SkillKit isn't just a package manager. It's a complete infrastructure for
|
||||
intelligent, distributed AI agent orchestration.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
{/* Feature Tabs */}
|
||||
<div className="flex justify-center gap-1 sm:gap-2 mb-8 flex-wrap" role="tablist" aria-label="Advanced features">
|
||||
{ADVANCED_FEATURES.map((f) => {
|
||||
const isActive = f.id === activeFeature;
|
||||
return (
|
||||
<button
|
||||
key={f.id}
|
||||
role="tab"
|
||||
aria-selected={isActive}
|
||||
aria-controls="advanced-features-panel"
|
||||
id={`tab-${f.id}`}
|
||||
onClick={() => setActiveFeature(f.id)}
|
||||
className={`group relative px-2 sm:px-4 py-1.5 sm:py-2 font-mono text-xs sm:text-sm transition-all duration-300 ${
|
||||
isActive
|
||||
? 'text-white'
|
||||
: 'text-zinc-500 hover:text-zinc-300'
|
||||
}`}
|
||||
>
|
||||
<span className="relative z-10">{f.title}</span>
|
||||
{isActive && (
|
||||
<div className="absolute inset-0 bg-gradient-to-r from-zinc-800 to-zinc-700 border border-zinc-600"></div>
|
||||
)}
|
||||
</button>
|
||||
);
|
||||
})}
|
||||
</div>
|
||||
|
||||
{/* Feature Content */}
|
||||
<div
|
||||
className="grid grid-cols-1 lg:grid-cols-2 gap-6 sm:gap-8 items-start"
|
||||
role="tabpanel"
|
||||
id="advanced-features-panel"
|
||||
aria-labelledby={`tab-${activeFeature}`}
|
||||
>
|
||||
{/* Left: Description */}
|
||||
<div className="space-y-4 sm:space-y-6">
|
||||
<div className="flex items-start gap-3 sm:gap-4">
|
||||
<div className="p-2 sm:p-3 bg-zinc-800/50 border border-zinc-700 text-white flex-shrink-0">
|
||||
{feature.icon}
|
||||
</div>
|
||||
<div>
|
||||
<h3 className="text-xl sm:text-2xl font-bold text-white font-mono mb-1">
|
||||
{feature.title}
|
||||
</h3>
|
||||
<p className="text-zinc-500 font-mono text-xs sm:text-sm">
|
||||
{feature.subtitle}
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<p className="text-zinc-300 leading-relaxed text-sm sm:text-base">
|
||||
{feature.description}
|
||||
</p>
|
||||
|
||||
<div className="inline-flex items-center gap-2 bg-emerald-950/30 border border-emerald-800/50 px-2 sm:px-3 py-1.5 sm:py-2">
|
||||
<svg className="w-3 h-3 sm:w-4 sm:h-4 text-emerald-400 flex-shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor">
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
|
||||
</svg>
|
||||
<span className="text-emerald-300 text-xs sm:text-sm font-mono">{feature.highlight}</span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{/* Right: Commands */}
|
||||
<div className="bg-black/60 border border-zinc-800 backdrop-blur-sm">
|
||||
<div className="flex items-center gap-1.5 px-4 py-3 border-b border-zinc-800 bg-zinc-900/50">
|
||||
<div className="w-3 h-3 rounded-full bg-zinc-700"></div>
|
||||
<div className="w-3 h-3 rounded-full bg-zinc-700"></div>
|
||||
<div className="w-3 h-3 rounded-full bg-zinc-700"></div>
|
||||
<span className="ml-2 text-zinc-500 text-xs font-mono">Terminal</span>
|
||||
</div>
|
||||
<div className="p-3 sm:p-4 space-y-3">
|
||||
{feature.commands.map((cmd, index) => (
|
||||
<div key={index} className="group">
|
||||
<div className="flex items-center gap-2 overflow-x-auto">
|
||||
<span className="text-zinc-600 font-mono text-xs flex-shrink-0">$</span>
|
||||
<code className="text-white font-mono text-xs sm:text-sm whitespace-nowrap">skillkit {cmd.cmd}</code>
|
||||
</div>
|
||||
<div className="pl-4 mt-1">
|
||||
<span className="text-zinc-500 font-mono text-[10px] sm:text-xs">→ {cmd.desc}</span>
|
||||
</div>
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{/* Bottom CTA */}
|
||||
<div className="mt-12 pt-8 border-t border-zinc-800/50 text-center">
|
||||
<p className="text-zinc-500 text-sm font-mono mb-4">
|
||||
Ready to supercharge your AI agents?
|
||||
</p>
|
||||
<code className="inline-block bg-zinc-900 border border-zinc-700 px-4 py-2 text-sm font-mono text-zinc-300">
|
||||
npx skillkit@latest
|
||||
</code>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
);
|
||||
}
|
||||
@@ -13,7 +13,7 @@ const COMMAND_GROUPS: CommandGroup[] = [
|
||||
{ cmd: 'install <repo>', desc: 'Install from GitHub' },
|
||||
{ cmd: 'add <repo>', desc: 'Alias for install' },
|
||||
{ cmd: 'recommend', desc: 'Smart suggestions' },
|
||||
{ cmd: 'find <query>', desc: 'Search 15K+ skills' },
|
||||
{ cmd: 'tree', desc: 'Browse skill taxonomy' },
|
||||
{ cmd: 'marketplace', desc: 'Browse skills' },
|
||||
],
|
||||
},
|
||||
|
||||
@@ -8,8 +8,8 @@ interface Feature {
|
||||
|
||||
const FEATURES: Feature[] = [
|
||||
{
|
||||
title: 'Primer',
|
||||
description: 'Generate AI instructions from codebase analysis.',
|
||||
title: 'Smart Recommendations',
|
||||
description: 'AI analyzes your codebase and suggests perfect 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" />
|
||||
@@ -17,85 +17,95 @@ const FEATURES: Feature[] = [
|
||||
)
|
||||
},
|
||||
{
|
||||
title: 'Multi-Agent',
|
||||
description: 'Deploy to 32 AI coding agents with one command.',
|
||||
title: 'Auto Translation',
|
||||
description: 'Write once, deploy to 32 agents. Zero manual conversion.',
|
||||
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="M19 11H5m14 0a2 2 0 012 2v6a2 2 0 01-2 2H5a2 2 0 01-2-2v-6a2 2 0 012-2m14 0V9a2 2 0 00-2-2M5 11V9a2 2 0 012-2m0 0V5a2 2 0 012-2h6a2 2 0 012 2v2M7 7h10" />
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M8 7h12m0 0l-4-4m4 4l-4 4m0 6H4m0 0l4 4m-4-4l4-4" />
|
||||
</svg>
|
||||
)
|
||||
},
|
||||
{
|
||||
title: 'Mesh Network',
|
||||
description: 'Multi-machine agent distribution with encrypted P2P.',
|
||||
title: 'Session Memory',
|
||||
description: 'AI learnings persist across sessions and projects.',
|
||||
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="M21 12a9 9 0 01-9 9m9-9a9 9 0 00-9-9m9 9H3m9 9a9 9 0 01-9-9m9 9c1.657 0 3-4.03 3-9s-1.343-9-3-9m0 18c-1.657 0-3-4.03-3-9s1.343-9 3-9m-9 9a9 9 0 019-9" />
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2" />
|
||||
</svg>
|
||||
)
|
||||
},
|
||||
{
|
||||
title: 'Security',
|
||||
description: 'Ed25519 signing, TLS, and encrypted storage.',
|
||||
title: 'Primer',
|
||||
description: 'Auto-generate agent instructions for all 32 agents from your codebase.',
|
||||
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="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z" />
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M13 10V3L4 14h7v7l9-11h-7z" />
|
||||
</svg>
|
||||
)
|
||||
},
|
||||
{
|
||||
title: 'Terminal UI',
|
||||
description: 'Beautiful interactive TUI for browsing & installing.',
|
||||
title: 'Skill Tree',
|
||||
description: 'Browse 15K+ skills in a hierarchical taxonomy with 12 categories.',
|
||||
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 9l3 3-3 3m5 0h3M5 20h14a2 2 0 002-2V6a2 2 0 00-2-2H5a2 2 0 00-2 2v12a2 2 0 002 2z" />
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M3 7v10a2 2 0 002 2h14a2 2 0 002-2V9a2 2 0 00-2-2h-6l-2-2H5a2 2 0 00-2 2z" />
|
||||
</svg>
|
||||
)
|
||||
},
|
||||
{
|
||||
title: 'Messaging',
|
||||
description: 'Inter-agent messaging across the mesh.',
|
||||
title: 'Workflows',
|
||||
description: 'Compose multi-step automated skill sequences.',
|
||||
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 10h.01M12 10h.01M16 10h.01M9 16H5a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v8a2 2 0 01-2 2h-5l-5 5v-5z" />
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M4 5a1 1 0 011-1h14a1 1 0 011 1v2a1 1 0 01-1 1H5a1 1 0 01-1-1V5zM4 13a1 1 0 011-1h6a1 1 0 011 1v6a1 1 0 01-1 1H5a1 1 0 01-1-1v-6zM16 13a1 1 0 011-1h2a1 1 0 011 1v6a1 1 0 01-1 1h-2a1 1 0 01-1-1v-6z" />
|
||||
</svg>
|
||||
)
|
||||
},
|
||||
{
|
||||
title: 'Plugins',
|
||||
description: 'Extend with custom plugins & hooks.',
|
||||
title: 'Team Sync',
|
||||
description: 'Git-based .skills manifest for consistency.',
|
||||
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="M17 14v6m-3-3h6M6 10h2a2 2 0 002-2V6a2 2 0 00-2-2H6a2 2 0 00-2 2v2a2 2 0 002 2zm10 0h2a2 2 0 002-2V6a2 2 0 00-2-2h-2a2 2 0 00-2 2v2a2 2 0 002 2zM6 20h2a2 2 0 002-2v-2a2 2 0 00-2-2H6a2 2 0 00-2 2v2a2 2 0 002 2z" />
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M17 20h5v-2a3 3 0 00-5.356-1.857M17 20H7m10 0v-2c0-.656-.126-1.283-.356-1.857M7 20H2v-2a3 3 0 015.356-1.857M7 20v-2c0-.656.126-1.283.356-1.857m0 0a5.002 5.002 0 019.288 0M15 7a3 3 0 11-6 0 3 3 0 016 0z" />
|
||||
</svg>
|
||||
)
|
||||
},
|
||||
{
|
||||
title: 'Manifest',
|
||||
description: '.skills file for team-wide consistency.',
|
||||
title: 'Testing',
|
||||
description: 'Built-in test framework with assertions.',
|
||||
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 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" />
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
|
||||
</svg>
|
||||
)
|
||||
},
|
||||
{
|
||||
title: 'Slash Commands',
|
||||
description: 'Generate /commands for Claude, Cursor & more.',
|
||||
title: 'CI/CD',
|
||||
description: 'GitHub Actions, GitLab CI, pre-commit.',
|
||||
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="M7 20l4-16m2 16l4-16M6 9h14M4 15h14" />
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M4 4v5h.582m15.356 2A8.001 8.001 0 004.582 9m0 0H9m11 11v-5h-.581m0 0a8.003 8.003 0 01-15.357-2m15.357 2H15" />
|
||||
</svg>
|
||||
)
|
||||
},
|
||||
{
|
||||
title: 'TS API',
|
||||
description: 'Programmatic access for custom tooling.',
|
||||
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="M10 20l4-16m4 4l4 4-4 4M6 16l-4-4 4-4" />
|
||||
</svg>
|
||||
)
|
||||
}
|
||||
];
|
||||
|
||||
const COMPARISONS = [
|
||||
['Agents', '1', '32'],
|
||||
['Instructions', 'Manual', 'Primer Auto'],
|
||||
['Translation', 'Manual', 'Auto'],
|
||||
['Sharing', 'Copy/paste', '.skills manifest'],
|
||||
['Discovery', 'Forums', 'CLI + AI'],
|
||||
['Agent Support', '1 agent', '32 agents'],
|
||||
['Setup', 'Write rules manually', 'Auto-generate (Primer)'],
|
||||
['Learning', 'Lost each session', 'Persistent memory'],
|
||||
['Translation', 'Rewrite for each', 'One-click conversion'],
|
||||
['Team Sharing', 'Copy/paste files', '.skills manifest'],
|
||||
['Discovery', 'Search forums', 'AI recommendations'],
|
||||
] as const;
|
||||
|
||||
export function Features(): React.ReactElement {
|
||||
@@ -114,11 +124,11 @@ export function Features(): React.ReactElement {
|
||||
<div className="text-zinc-600 text-[10px] sm:text-xs font-mono">Agents</div>
|
||||
</div>
|
||||
<div>
|
||||
<div className="text-2xl sm:text-3xl font-bold text-white font-mono">40+</div>
|
||||
<div className="text-2xl sm:text-3xl font-bold text-white font-mono">50+</div>
|
||||
<div className="text-zinc-600 text-[10px] sm:text-xs font-mono">Commands</div>
|
||||
</div>
|
||||
<div>
|
||||
<div className="text-2xl sm:text-3xl font-bold text-white font-mono">15K</div>
|
||||
<div className="text-2xl sm:text-3xl font-bold text-white font-mono">15K+</div>
|
||||
<div className="text-zinc-600 text-[10px] sm:text-xs font-mono">Skills</div>
|
||||
</div>
|
||||
</div>
|
||||
@@ -146,7 +156,7 @@ export function Features(): React.ReactElement {
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div className="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-5 gap-3">
|
||||
<div className="grid grid-cols-2 sm:grid-cols-3 gap-3">
|
||||
{FEATURES.map((feature, index) => (
|
||||
<div
|
||||
key={feature.title}
|
||||
|
||||
@@ -1,6 +1,10 @@
|
||||
import React, { useState, useEffect } from 'react';
|
||||
import { Button } from './Button';
|
||||
|
||||
interface HeroProps {
|
||||
version: string;
|
||||
}
|
||||
|
||||
const ASCII_LOGO = `
|
||||
███████╗██╗ ██╗██╗██╗ ██╗ ██╗ ██╗██╗████████╗
|
||||
██╔════╝██║ ██╔╝██║██║ ██║ ██║ ██╔╝██║╚══██╔══╝
|
||||
@@ -16,15 +20,17 @@ interface TerminalLine {
|
||||
}
|
||||
|
||||
const TERMINAL_LINES: TerminalLine[] = [
|
||||
{ type: 'cmd', text: 'skillkit primer --all-agents' },
|
||||
{ type: 'out', text: '→ Analyzing codebase...' },
|
||||
{ type: 'out', text: ' ✓ Generated CLAUDE.md' },
|
||||
{ type: 'out', text: ' ✓ Generated .cursorrules' },
|
||||
{ type: 'cmd', text: 'skillkit recommend' },
|
||||
{ type: 'out', text: ' 92% react-best-practices' },
|
||||
{ type: 'out', text: ' 87% typescript-strict' },
|
||||
{ type: 'cmd', text: 'skillkit install anthropics/skills' },
|
||||
{ type: 'out', text: '→ Installed 3 skills' },
|
||||
{ type: 'cmd', text: 'skillkit sync --agent cursor,claude' },
|
||||
{ type: 'out', text: ' ✓ Synced to 2 agents' },
|
||||
{ type: 'cmd', text: 'skillkit translate my-skill --to codex' },
|
||||
{ type: 'out', text: '→ Converted to SKILL.md format' },
|
||||
{ type: 'out', text: ' 92% vercel-react-best-practices' },
|
||||
{ type: 'out', text: ' 87% typescript-strict-mode' },
|
||||
{ type: 'cmd', text: 'skillkit install anthropics/skills --agent all' },
|
||||
{ type: 'out', text: '→ Installed to 32 agents' },
|
||||
{ type: 'cmd', text: 'skillkit memory compress' },
|
||||
{ type: 'out', text: '→ 12 learnings persisted' },
|
||||
];
|
||||
|
||||
const FADE_ANIMATION_STYLES = `
|
||||
@@ -53,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);
|
||||
@@ -124,17 +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">
|
||||
Universal Skills for<br />
|
||||
<span className="text-zinc-500">AI Coding Agents</span>
|
||||
Write Once.<br />
|
||||
<span className="text-zinc-500">Deploy to 32 Agents.</span>
|
||||
</h1>
|
||||
|
||||
<p className="text-sm text-zinc-400 mb-5 max-w-lg font-mono leading-relaxed">
|
||||
One CLI to install, sync, and manage skills across Claude Code, Cursor,
|
||||
Windsurf, Copilot, and 28 more agents. 15,000+ skills ready to use.
|
||||
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.
|
||||
</p>
|
||||
|
||||
<div className="flex flex-wrap items-center gap-3 mb-4">
|
||||
@@ -203,6 +210,32 @@ export function Hero(): React.ReactElement {
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{/* Video Demo */}
|
||||
<div className="mt-8 sm:mt-10 animate-fade-in-delay">
|
||||
<div className="relative mx-auto max-w-3xl">
|
||||
<div className="absolute -inset-1 bg-gradient-to-r from-zinc-800 via-zinc-600 to-zinc-800 rounded-lg opacity-30 blur-xl"></div>
|
||||
<div className="relative border border-zinc-800 bg-black rounded-lg overflow-hidden">
|
||||
<div className="flex items-center gap-1.5 px-3 py-2 border-b border-zinc-800 bg-zinc-900/50">
|
||||
<div className="w-2.5 h-2.5 rounded-full bg-red-500/80"></div>
|
||||
<div className="w-2.5 h-2.5 rounded-full bg-yellow-500/80"></div>
|
||||
<div className="w-2.5 h-2.5 rounded-full bg-green-500/80"></div>
|
||||
<span className="ml-2 text-zinc-500 text-xs font-mono">skillkit demo</span>
|
||||
</div>
|
||||
<video
|
||||
className="w-full"
|
||||
autoPlay
|
||||
loop
|
||||
muted
|
||||
playsInline
|
||||
poster="/og-image.png"
|
||||
>
|
||||
<source src="/skillkit.mp4" type="video/mp4" />
|
||||
Your browser does not support the video tag.
|
||||
</video>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<style>{FADE_ANIMATION_STYLES}</style>
|
||||
|
||||
@@ -1,10 +1,13 @@
|
||||
import React, { useState } from 'react';
|
||||
import React, { useState, useEffect } from 'react';
|
||||
import { searchSkills, IndexedSkill, SKILLS_INDEX } from '../data/skills-index';
|
||||
|
||||
interface StackItem extends IndexedSkill {
|
||||
addedAt: number;
|
||||
}
|
||||
|
||||
// Default starter skills to show on load
|
||||
const DEFAULT_SKILLS = ['react', 'typescript', 'nextjs'];
|
||||
|
||||
const POPULAR_STACKS = [
|
||||
{
|
||||
name: 'Full Stack TypeScript',
|
||||
@@ -54,6 +57,20 @@ export function StackBuilder(): React.ReactElement {
|
||||
const [searchResults, setSearchResults] = useState<IndexedSkill[]>([]);
|
||||
const [copied, setCopied] = useState(false);
|
||||
|
||||
// Load default skills on mount
|
||||
useEffect(() => {
|
||||
const initialStack: StackItem[] = [];
|
||||
DEFAULT_SKILLS.forEach(query => {
|
||||
const results = searchSkills(query);
|
||||
if (results.length > 0 && !initialStack.some(s => s.id === results[0].id)) {
|
||||
initialStack.push({ ...results[0], addedAt: Date.now() });
|
||||
}
|
||||
});
|
||||
if (initialStack.length > 0) {
|
||||
setStack(initialStack);
|
||||
}
|
||||
}, []);
|
||||
|
||||
function handleSearch(query: string): void {
|
||||
setSearchQuery(query);
|
||||
if (query.trim()) {
|
||||
|
||||
@@ -0,0 +1,125 @@
|
||||
import React from 'react';
|
||||
|
||||
interface TeamFeature {
|
||||
title: string;
|
||||
description: string;
|
||||
icon: React.ReactNode;
|
||||
}
|
||||
|
||||
const TEAM_FEATURES: TeamFeature[] = [
|
||||
{
|
||||
title: '.skills Manifest',
|
||||
description: 'Define your team\'s skill stack in a single file. Everyone gets the same capabilities.',
|
||||
icon: (
|
||||
<svg className="w-6 h-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" />
|
||||
</svg>
|
||||
),
|
||||
},
|
||||
{
|
||||
title: 'Git-Based Sync',
|
||||
description: 'Skills live in your repo. Push to share. Pull to update. Works with your existing workflow.',
|
||||
icon: (
|
||||
<svg className="w-6 h-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M8 7v8a2 2 0 002 2h6M8 7V5a2 2 0 012-2h4.586a1 1 0 01.707.293l4.414 4.414a1 1 0 01.293.707V15a2 2 0 01-2 2h-2M8 7H6a2 2 0 00-2 2v10a2 2 0 002 2h8a2 2 0 002-2v-2" />
|
||||
</svg>
|
||||
),
|
||||
},
|
||||
{
|
||||
title: 'CI/CD Integration',
|
||||
description: 'Auto-validate and deploy skills on every commit. GitHub Actions, GitLab CI, pre-commit hooks.',
|
||||
icon: (
|
||||
<svg className="w-6 h-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M4 4v5h.582m15.356 2A8.001 8.001 0 004.582 9m0 0H9m11 11v-5h-.581m0 0a8.003 8.003 0 01-15.357-2m15.357 2H15" />
|
||||
</svg>
|
||||
),
|
||||
},
|
||||
{
|
||||
title: 'Private Registries',
|
||||
description: 'Host internal skills in private repos. Control access and maintain proprietary knowledge.',
|
||||
icon: (
|
||||
<svg className="w-6 h-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z" />
|
||||
</svg>
|
||||
),
|
||||
},
|
||||
];
|
||||
|
||||
export function TeamEnterprise(): React.ReactElement {
|
||||
return (
|
||||
<section className="py-12 sm:py-16 border-b border-zinc-800 bg-gradient-to-b from-zinc-950 to-black">
|
||||
<div className="mx-auto max-w-5xl px-4 sm:px-6 lg:px-8">
|
||||
{/* Section Header */}
|
||||
<div className="text-center mb-8 sm:mb-12">
|
||||
<div className="inline-flex items-center gap-2 border border-zinc-700 bg-zinc-900/80 px-2 sm:px-3 py-1 mb-4 backdrop-blur-sm">
|
||||
<span className="text-[10px] sm:text-xs font-mono text-zinc-300 uppercase tracking-wider">For Teams</span>
|
||||
</div>
|
||||
<h2 className="text-2xl sm:text-3xl lg:text-4xl font-bold text-white mb-3 font-mono tracking-tight">
|
||||
Scale Across Your Organization
|
||||
</h2>
|
||||
<p className="text-zinc-400 font-mono text-xs sm:text-sm max-w-2xl mx-auto">
|
||||
From solo developers to enterprise teams. SkillKit grows with you.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
{/* Team Features Grid */}
|
||||
<div className="grid grid-cols-1 md:grid-cols-2 gap-3 sm:gap-4 mb-8 sm:mb-12">
|
||||
{TEAM_FEATURES.map((feature, index) => (
|
||||
<div
|
||||
key={index}
|
||||
className="group p-4 sm:p-5 border border-zinc-800 bg-zinc-900/30 hover:border-zinc-700 hover:bg-zinc-900/60 transition-all duration-300"
|
||||
>
|
||||
<div className="flex items-start gap-3 sm:gap-4">
|
||||
<div className="p-2 bg-zinc-800/50 border border-zinc-700 text-zinc-400 group-hover:text-white transition-colors flex-shrink-0">
|
||||
{feature.icon}
|
||||
</div>
|
||||
<div>
|
||||
<h3 className="text-base sm:text-lg font-bold text-white font-mono mb-1">{feature.title}</h3>
|
||||
<p className="text-zinc-500 text-xs sm:text-sm">{feature.description}</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
|
||||
{/* API Teaser */}
|
||||
<div className="border border-zinc-800 bg-black/30 p-4 sm:p-6">
|
||||
<div className="flex flex-col sm:flex-row items-start sm:items-center justify-between gap-4">
|
||||
<div>
|
||||
<h3 className="text-base sm:text-lg font-bold text-white font-mono mb-1">TypeScript API</h3>
|
||||
<p className="text-zinc-500 text-xs sm:text-sm">
|
||||
Full programmatic access. Import <code className="text-zinc-400">translateSkill</code>, <code className="text-zinc-400">analyzeProject</code> and more.
|
||||
</p>
|
||||
</div>
|
||||
<a
|
||||
href="https://agenstskills.com/docs/api-reference"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
className="inline-flex items-center gap-2 px-3 sm:px-4 py-2 bg-zinc-800 text-white font-mono text-xs sm:text-sm hover:bg-zinc-700 transition-colors border border-zinc-700 whitespace-nowrap"
|
||||
>
|
||||
<span>View API</span>
|
||||
<svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5l7 7-7 7" />
|
||||
</svg>
|
||||
</a>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{/* Bottom CTA */}
|
||||
<div className="mt-6 sm:mt-8 text-center">
|
||||
<a
|
||||
href="https://agenstskills.com/docs"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
className="inline-flex items-center gap-2 px-4 sm:px-6 py-2.5 sm:py-3 bg-white text-black font-mono text-xs sm:text-sm hover:bg-zinc-200 transition-colors cursor-pointer"
|
||||
>
|
||||
<span>Read the Documentation</span>
|
||||
<svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5l7 7-7 7" />
|
||||
</svg>
|
||||
</a>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,158 @@
|
||||
import React from 'react';
|
||||
|
||||
interface UseCase {
|
||||
persona: string;
|
||||
problem: string;
|
||||
solution: string;
|
||||
command: string;
|
||||
icon: React.ReactNode;
|
||||
gradient: string;
|
||||
}
|
||||
|
||||
const USE_CASES: UseCase[] = [
|
||||
{
|
||||
persona: 'Multi-Agent Developer',
|
||||
problem: 'You\'ve built skills for Claude Code. Now your team wants Cursor, and you want to try Windsurf.',
|
||||
solution: 'SkillKit translates skills between all 32 agents. Write once, deploy everywhere.',
|
||||
command: 'skillkit translate --to cursor,windsurf',
|
||||
gradient: 'from-violet-500/10 to-purple-500/10',
|
||||
icon: (
|
||||
<svg className="w-6 h-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z" />
|
||||
</svg>
|
||||
),
|
||||
},
|
||||
{
|
||||
persona: 'Team Lead',
|
||||
problem: 'Each developer has different skills. Onboarding takes weeks. Knowledge is scattered.',
|
||||
solution: 'Shared .skills manifest ensures everyone has the same capabilities. Git-based sync keeps teams aligned.',
|
||||
command: 'skillkit team init && skillkit team share',
|
||||
gradient: 'from-blue-500/10 to-cyan-500/10',
|
||||
icon: (
|
||||
<svg className="w-6 h-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M17 20h5v-2a3 3 0 00-5.356-1.857M17 20H7m10 0v-2c0-.656-.126-1.283-.356-1.857M7 20H2v-2a3 3 0 015.356-1.857M7 20v-2c0-.656.126-1.283.356-1.857m0 0a5.002 5.002 0 019.288 0M15 7a3 3 0 11-6 0 3 3 0 016 0zm6 3a2 2 0 11-4 0 2 2 0 014 0zM7 10a2 2 0 11-4 0 2 2 0 014 0z" />
|
||||
</svg>
|
||||
),
|
||||
},
|
||||
{
|
||||
persona: 'New Project Starter',
|
||||
problem: 'Configuring AI agents for each new project is tedious. You forget best practices.',
|
||||
solution: 'Primer analyzes your codebase and auto-generates optimized instructions for all agents.',
|
||||
command: 'skillkit primer --all-agents',
|
||||
gradient: 'from-emerald-500/10 to-teal-500/10',
|
||||
icon: (
|
||||
<svg className="w-6 h-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M13 10V3L4 14h7v7l9-11h-7z" />
|
||||
</svg>
|
||||
),
|
||||
},
|
||||
{
|
||||
persona: 'Enterprise Architect',
|
||||
problem: 'Running AI agents across multiple machines and keeping them in sync is a nightmare.',
|
||||
solution: 'Mesh network with encrypted P2P, peer trust, and inter-agent messaging.',
|
||||
command: 'skillkit mesh init && skillkit mesh discover',
|
||||
gradient: 'from-orange-500/10 to-amber-500/10',
|
||||
icon: (
|
||||
<svg className="w-6 h-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M19 11H5m14 0a2 2 0 012 2v6a2 2 0 01-2 2H5a2 2 0 01-2-2v-6a2 2 0 012-2m14 0V9a2 2 0 00-2-2M5 11V9a2 2 0 012-2m0 0V5a2 2 0 012-2h6a2 2 0 012 2v2M7 7h10" />
|
||||
</svg>
|
||||
),
|
||||
},
|
||||
];
|
||||
|
||||
const WORKFLOW_FEATURES = [
|
||||
{
|
||||
title: 'Workflow Orchestration',
|
||||
description: 'Compose skills into multi-step workflows. Chain operations, handle errors, and automate complex tasks.',
|
||||
command: 'skillkit workflow run feature-development',
|
||||
},
|
||||
{
|
||||
title: 'Skill Testing',
|
||||
description: 'Built-in test framework with assertions. Validate skills work correctly before deployment.',
|
||||
command: 'skillkit test --tags unit,integration',
|
||||
},
|
||||
{
|
||||
title: 'CI/CD Integration',
|
||||
description: 'Generate GitHub Actions, GitLab CI, and pre-commit hooks for automated skill management.',
|
||||
command: 'skillkit cicd init --provider github',
|
||||
},
|
||||
{
|
||||
title: 'Slash Commands',
|
||||
description: 'Auto-generate /commands for Claude, Cursor, and other agents from your skills.',
|
||||
command: 'skillkit command generate',
|
||||
},
|
||||
];
|
||||
|
||||
export function UseCases(): React.ReactElement {
|
||||
return (
|
||||
<section className="py-12 sm:py-16 border-b border-zinc-800 bg-zinc-950">
|
||||
<div className="mx-auto max-w-5xl px-4 sm:px-6 lg:px-8">
|
||||
{/* Section Header */}
|
||||
<div className="text-center mb-8 sm:mb-12">
|
||||
<h2 className="text-2xl sm:text-3xl lg:text-4xl font-bold text-white mb-3 font-mono tracking-tight">
|
||||
Built for Real Workflows
|
||||
</h2>
|
||||
<p className="text-zinc-400 font-mono text-xs sm:text-sm max-w-2xl mx-auto">
|
||||
Whether you're a solo developer or managing enterprise infrastructure,
|
||||
SkillKit adapts to your needs.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
{/* Use Cases Grid */}
|
||||
<div className="grid grid-cols-1 md:grid-cols-2 gap-3 sm:gap-4 mb-12">
|
||||
{USE_CASES.map((useCase, index) => (
|
||||
<div
|
||||
key={index}
|
||||
className={`relative group p-4 sm:p-6 border border-zinc-800 bg-gradient-to-br ${useCase.gradient} hover:border-zinc-700 transition-all duration-300`}
|
||||
>
|
||||
<div className="flex items-start gap-3 sm:gap-4 mb-4">
|
||||
<div className="p-2 bg-zinc-800/80 border border-zinc-700 text-zinc-300 group-hover:text-white transition-colors flex-shrink-0">
|
||||
{useCase.icon}
|
||||
</div>
|
||||
<div>
|
||||
<h3 className="text-base sm:text-lg font-bold text-white font-mono">{useCase.persona}</h3>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div className="space-y-3">
|
||||
<div className="flex items-start gap-2">
|
||||
<span className="text-red-400 text-[10px] sm:text-xs mt-0.5 font-mono flex-shrink-0">PAIN:</span>
|
||||
<p className="text-zinc-400 text-xs sm:text-sm">{useCase.problem}</p>
|
||||
</div>
|
||||
<div className="flex items-start gap-2">
|
||||
<span className="text-emerald-400 text-[10px] sm:text-xs mt-0.5 font-mono flex-shrink-0">FIX:</span>
|
||||
<p className="text-zinc-300 text-xs sm:text-sm">{useCase.solution}</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div className="mt-4 pt-4 border-t border-zinc-800/50">
|
||||
<code className="text-[10px] sm:text-xs font-mono text-zinc-500 bg-black/30 px-2 py-1 block overflow-x-auto whitespace-nowrap">
|
||||
$ {useCase.command}
|
||||
</code>
|
||||
</div>
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
|
||||
{/* Workflow Features */}
|
||||
<div className="border border-zinc-800 bg-black/30 p-4 sm:p-6">
|
||||
<h3 className="text-base sm:text-lg font-bold text-white mb-4 sm:mb-6 font-mono text-center">
|
||||
Developer Tools Built-In
|
||||
</h3>
|
||||
<div className="grid grid-cols-1 sm:grid-cols-2 gap-3 sm:gap-4">
|
||||
{WORKFLOW_FEATURES.map((feature, index) => (
|
||||
<div key={index} className="flex items-start gap-2 sm:gap-3 p-2 sm:p-3 hover:bg-zinc-900/50 transition-colors">
|
||||
<span className="text-zinc-500 mt-1 flex-shrink-0">▸</span>
|
||||
<div className="min-w-0">
|
||||
<h4 className="text-xs sm:text-sm font-bold text-white font-mono mb-1">{feature.title}</h4>
|
||||
<p className="text-[10px] sm:text-xs text-zinc-500 mb-2">{feature.description}</p>
|
||||
<code className="text-[9px] sm:text-[10px] font-mono text-zinc-600 break-all">{feature.command}</code>
|
||||
</div>
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
);
|
||||
}
|
||||
@@ -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;
|
||||
}
|
||||
@@ -4,20 +4,24 @@
|
||||
<meta charset="UTF-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>SkillKit - Universal Skills for AI Coding Agents</title>
|
||||
<meta name="description" content="Portable, reusable skills that work across Claude Code, Cursor, Codex, Windsurf, GitHub Copilot, and 12 more AI coding agents.">
|
||||
<meta name="description" content="Write once, deploy to 32 AI coding agents. Skills for Claude Code, Cursor, Codex, Windsurf, GitHub Copilot, and more.">
|
||||
|
||||
<!-- Open Graph -->
|
||||
<meta property="og:type" content="website">
|
||||
<meta property="og:url" content="https://skillkit.dev/">
|
||||
<meta property="og:url" content="https://agenstskills.com/">
|
||||
<meta property="og:title" content="SkillKit - Universal Skills for AI Coding Agents">
|
||||
<meta property="og:description" content="Portable, reusable skills that work across Claude Code, Cursor, Codex, Windsurf, GitHub Copilot, and 12 more AI coding agents.">
|
||||
<meta property="og:image" content="/og-image.png">
|
||||
<meta property="og:description" content="Write once, deploy to 32 AI coding agents. Skills for Claude Code, Cursor, Codex, Windsurf, GitHub Copilot, and more.">
|
||||
<meta property="og:image" content="https://agenstskills.com/og-image.png">
|
||||
<meta property="og:image:width" content="1200">
|
||||
<meta property="og:image:height" content="630">
|
||||
<meta property="og:site_name" content="SkillKit">
|
||||
|
||||
<!-- Twitter -->
|
||||
<meta name="twitter:card" content="summary_large_image">
|
||||
<meta name="twitter:url" content="https://agenstskills.com/">
|
||||
<meta name="twitter:title" content="SkillKit - Universal Skills for AI Coding Agents">
|
||||
<meta name="twitter:description" content="Portable, reusable skills that work across Claude Code, Cursor, Codex, Windsurf, GitHub Copilot, and 12 more AI coding agents.">
|
||||
<meta name="twitter:image" content="/og-image.png">
|
||||
<meta name="twitter:description" content="Write once, deploy to 32 AI coding agents. Skills for Claude Code, Cursor, Codex, Windsurf, GitHub Copilot, and more.">
|
||||
<meta name="twitter:image" content="https://agenstskills.com/og-image.png">
|
||||
|
||||
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
|
||||
<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32.png" />
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "skillkit",
|
||||
"private": true,
|
||||
"version": "1.8.0",
|
||||
"version": "1.10.0",
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"dev": "vite",
|
||||
|
||||
Binary file not shown.
@@ -3,11 +3,11 @@
|
||||
body {
|
||||
background-color: #000000;
|
||||
color: #e4e4e7;
|
||||
font-family: 'Inter', sans-serif;
|
||||
font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
|
||||
}
|
||||
|
||||
h1, h2, h3, h4, h5, h6, .font-mono {
|
||||
font-family: 'JetBrains Mono', monospace;
|
||||
font-family: 'JetBrains Mono', 'SF Mono', 'Fira Code', monospace;
|
||||
}
|
||||
|
||||
::selection {
|
||||
@@ -29,6 +29,18 @@ h1, h2, h3, h4, h5, h6, .font-mono {
|
||||
background: #3f3f46;
|
||||
}
|
||||
|
||||
/* Smooth scrolling - respects user preferences */
|
||||
html {
|
||||
scroll-behavior: smooth;
|
||||
}
|
||||
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
html {
|
||||
scroll-behavior: auto;
|
||||
}
|
||||
}
|
||||
|
||||
/* Terminal scanline effect */
|
||||
.terminal-scanline {
|
||||
background: linear-gradient(to bottom, rgba(255,255,255,0), rgba(255,255,255,0) 50%, rgba(0,0,0,0.1) 50%, rgba(0,0,0,0.1));
|
||||
background-size: 100% 4px;
|
||||
@@ -41,3 +53,58 @@ h1, h2, h3, h4, h5, h6, .font-mono {
|
||||
z-index: 10;
|
||||
opacity: 0.1;
|
||||
}
|
||||
|
||||
/* Glow effect for important elements */
|
||||
.glow-effect {
|
||||
box-shadow: 0 0 40px rgba(255, 255, 255, 0.03);
|
||||
}
|
||||
|
||||
/* Subtle gradient animation for hero */
|
||||
@keyframes gradient-shift {
|
||||
0%, 100% {
|
||||
background-position: 0% 50%;
|
||||
}
|
||||
50% {
|
||||
background-position: 100% 50%;
|
||||
}
|
||||
}
|
||||
|
||||
.gradient-animate {
|
||||
background-size: 200% 200%;
|
||||
animation: gradient-shift 15s ease infinite;
|
||||
}
|
||||
|
||||
/* Grid pattern overlay */
|
||||
.grid-pattern {
|
||||
background-image:
|
||||
linear-gradient(rgba(255, 255, 255, 0.02) 1px, transparent 1px),
|
||||
linear-gradient(90deg, rgba(255, 255, 255, 0.02) 1px, transparent 1px);
|
||||
background-size: 60px 60px;
|
||||
}
|
||||
|
||||
/* Text shadow for headings */
|
||||
.text-glow {
|
||||
text-shadow: 0 0 60px rgba(255, 255, 255, 0.1);
|
||||
}
|
||||
|
||||
/* Hover scale animation */
|
||||
.hover-lift {
|
||||
transition: transform 0.3s ease, box-shadow 0.3s ease;
|
||||
}
|
||||
|
||||
.hover-lift:hover {
|
||||
transform: translateY(-2px);
|
||||
box-shadow: 0 10px 40px rgba(0, 0, 0, 0.4);
|
||||
}
|
||||
|
||||
/* Border gradient effect */
|
||||
.border-gradient {
|
||||
background: linear-gradient(135deg, rgba(255, 255, 255, 0.1), rgba(255, 255, 255, 0.03));
|
||||
background-clip: padding-box;
|
||||
}
|
||||
|
||||
/* Focus ring for accessibility */
|
||||
*:focus-visible {
|
||||
outline: 2px solid rgba(255, 255, 255, 0.5);
|
||||
outline-offset: 2px;
|
||||
}
|
||||
|
||||
+19
-2
@@ -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",
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "skillkit-monorepo",
|
||||
"version": "1.8.0",
|
||||
"version": "1.10.0",
|
||||
"private": true,
|
||||
"description": "Universal skills loader for AI coding agents - Monorepo",
|
||||
"type": "module",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@skillkit/agents",
|
||||
"version": "1.8.0",
|
||||
"version": "1.10.0",
|
||||
"description": "Agent adapters for SkillKit - supports 32 AI coding agents",
|
||||
"type": "module",
|
||||
"main": "./dist/index.js",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@skillkit/cli",
|
||||
"version": "1.8.0",
|
||||
"version": "1.10.0",
|
||||
"description": "CLI commands for SkillKit",
|
||||
"type": "module",
|
||||
"main": "./dist/index.js",
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
import chalk from 'chalk';
|
||||
import { Command, Option } from 'clipanion';
|
||||
import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
|
||||
import { join } from 'node:path';
|
||||
import { join, basename } from 'node:path';
|
||||
import { homedir } from 'node:os';
|
||||
import {
|
||||
findAllAgents,
|
||||
@@ -17,8 +17,14 @@ import {
|
||||
validateAgent,
|
||||
translateAgent,
|
||||
getAgentTargetDirectory,
|
||||
discoverSkills,
|
||||
readSkillContent,
|
||||
generateSubagentFromSkill,
|
||||
type CustomAgent,
|
||||
type AgentType,
|
||||
type Skill,
|
||||
type AgentPermissionMode,
|
||||
type SkillToSubagentOptions,
|
||||
} from '@skillkit/core';
|
||||
import {
|
||||
getBundledAgents,
|
||||
@@ -28,7 +34,6 @@ import {
|
||||
isAgentInstalled,
|
||||
type BundledAgent,
|
||||
} from '@skillkit/resources';
|
||||
// Agent discovery uses root directories, not skill directories
|
||||
|
||||
export class AgentCommand extends Command {
|
||||
static override paths = [['agent']];
|
||||
@@ -43,17 +48,19 @@ export class AgentCommand extends Command {
|
||||
that can be invoked with @mentions or the --agent flag.
|
||||
|
||||
Sub-commands:
|
||||
agent list - List all installed agents
|
||||
agent show - Show agent details
|
||||
agent create - Create a new agent
|
||||
agent translate - Translate agents between formats
|
||||
agent sync - Sync agents to target AI agent
|
||||
agent validate - Validate agent definitions
|
||||
agent list - List all installed agents
|
||||
agent show - Show agent details
|
||||
agent create - Create a new agent
|
||||
agent from-skill - Convert a skill to a subagent
|
||||
agent translate - Translate agents between formats
|
||||
agent sync - Sync agents to target AI agent
|
||||
agent validate - Validate agent definitions
|
||||
`,
|
||||
examples: [
|
||||
['List all agents', '$0 agent list'],
|
||||
['Show agent details', '$0 agent show architect'],
|
||||
['Create new agent', '$0 agent create security-reviewer'],
|
||||
['Convert skill to subagent', '$0 agent from-skill code-simplifier'],
|
||||
['Translate to Cursor format', '$0 agent translate --to cursor'],
|
||||
['Sync agents', '$0 agent sync --agent claude-code'],
|
||||
],
|
||||
@@ -64,6 +71,7 @@ export class AgentCommand extends Command {
|
||||
console.log(' agent list List all installed agents');
|
||||
console.log(' agent show <name> Show agent details');
|
||||
console.log(' agent create <name> Create a new agent');
|
||||
console.log(' agent from-skill <name> Convert a skill to a subagent');
|
||||
console.log(' agent translate Translate agents between formats');
|
||||
console.log(' agent sync Sync agents to target AI agent');
|
||||
console.log(' agent validate [path] Validate agent definitions');
|
||||
@@ -254,7 +262,6 @@ export class AgentCreateCommand extends Command {
|
||||
});
|
||||
|
||||
async execute(): Promise<number> {
|
||||
// Validate agent name format
|
||||
const namePattern = /^[a-z0-9]+(-[a-z0-9]+)*$/;
|
||||
if (!namePattern.test(this.name)) {
|
||||
console.log(chalk.red('Invalid agent name: must be lowercase alphanumeric with hyphens'));
|
||||
@@ -262,7 +269,6 @@ export class AgentCreateCommand extends Command {
|
||||
return 1;
|
||||
}
|
||||
|
||||
// Determine target directory
|
||||
let targetDir: string;
|
||||
if (this.global) {
|
||||
targetDir = join(homedir(), '.claude', 'agents');
|
||||
@@ -270,23 +276,19 @@ export class AgentCreateCommand extends Command {
|
||||
targetDir = join(process.cwd(), '.claude', 'agents');
|
||||
}
|
||||
|
||||
// Create directory if needed
|
||||
if (!existsSync(targetDir)) {
|
||||
mkdirSync(targetDir, { recursive: true });
|
||||
}
|
||||
|
||||
// Check if agent already exists
|
||||
const agentPath = join(targetDir, `${this.name}.md`);
|
||||
if (existsSync(agentPath)) {
|
||||
console.log(chalk.red(`Agent already exists: ${agentPath}`));
|
||||
return 1;
|
||||
}
|
||||
|
||||
// Generate content
|
||||
const description = this.description || `${this.name} agent`;
|
||||
const content = generateAgentTemplate(this.name, description, this.model);
|
||||
|
||||
// Write file
|
||||
writeFileSync(agentPath, content);
|
||||
|
||||
console.log(chalk.green(`Created agent: ${agentPath}`));
|
||||
@@ -350,11 +352,9 @@ export class AgentTranslateCommand extends Command {
|
||||
const searchDirs = [process.cwd()];
|
||||
const targetAgent = this.to as AgentType;
|
||||
|
||||
// Get agents to translate
|
||||
let agents: CustomAgent[];
|
||||
|
||||
if (this.source) {
|
||||
// Translate from custom source path
|
||||
const sourcePath = this.source.startsWith('/')
|
||||
? this.source
|
||||
: join(process.cwd(), this.source);
|
||||
@@ -391,7 +391,6 @@ export class AgentTranslateCommand extends Command {
|
||||
return 0;
|
||||
}
|
||||
|
||||
// Determine output directory
|
||||
const outputDir = this.output || getAgentTargetDirectory(process.cwd(), targetAgent);
|
||||
|
||||
console.log(chalk.cyan(`Translating ${agents.length} agent(s) to ${targetAgent} format...\n`));
|
||||
@@ -424,7 +423,6 @@ export class AgentTranslateCommand extends Command {
|
||||
}
|
||||
}
|
||||
} else {
|
||||
// Create directory if needed
|
||||
if (!existsSync(outputDir)) {
|
||||
mkdirSync(outputDir, { recursive: true });
|
||||
}
|
||||
@@ -529,12 +527,10 @@ export class AgentValidateCommand extends Command {
|
||||
let hasErrors = false;
|
||||
|
||||
if (this.agentPath) {
|
||||
// Validate specific path
|
||||
const result = validateAgent(this.agentPath);
|
||||
printValidationResult(this.agentPath, result);
|
||||
hasErrors = !result.valid;
|
||||
} else if (this.all) {
|
||||
// Validate all agents
|
||||
const searchDirs = [process.cwd()];
|
||||
const agents = findAllAgents(searchDirs);
|
||||
|
||||
@@ -559,8 +555,6 @@ export class AgentValidateCommand extends Command {
|
||||
}
|
||||
}
|
||||
|
||||
// Helper functions
|
||||
|
||||
function printAgent(agent: CustomAgent): void {
|
||||
const status = agent.enabled ? chalk.green('✓') : chalk.red('○');
|
||||
const name = agent.enabled ? agent.name : chalk.dim(agent.name);
|
||||
@@ -831,9 +825,180 @@ export class AgentAvailableCommand extends Command {
|
||||
}
|
||||
}
|
||||
|
||||
export class AgentFromSkillCommand extends Command {
|
||||
static override paths = [['agent', 'from-skill']];
|
||||
|
||||
static override usage = Command.Usage({
|
||||
description: 'Convert a skill into a Claude Code subagent',
|
||||
details: `
|
||||
Converts a SkillKit skill into a Claude Code native subagent format.
|
||||
The generated .md file can be used with @mentions in Claude Code.
|
||||
|
||||
By default, the subagent references the skill (skills: [skill-name]).
|
||||
Use --inline to embed the full skill content in the system prompt.
|
||||
`,
|
||||
examples: [
|
||||
['Convert skill to subagent', '$0 agent from-skill code-simplifier'],
|
||||
['Create global subagent', '$0 agent from-skill code-simplifier --global'],
|
||||
['Embed skill content inline', '$0 agent from-skill code-simplifier --inline'],
|
||||
['Set model for subagent', '$0 agent from-skill code-simplifier --model opus'],
|
||||
['Preview without writing', '$0 agent from-skill code-simplifier --dry-run'],
|
||||
],
|
||||
});
|
||||
|
||||
skillName = Option.String({ required: true });
|
||||
|
||||
inline = Option.Boolean('--inline,-i', false, {
|
||||
description: 'Embed full skill content in system prompt',
|
||||
});
|
||||
|
||||
model = Option.String('--model,-m', {
|
||||
description: 'Model to use (sonnet, opus, haiku, inherit)',
|
||||
});
|
||||
|
||||
permission = Option.String('--permission,-p', {
|
||||
description: 'Permission mode (default, plan, auto-edit, full-auto, bypassPermissions)',
|
||||
});
|
||||
|
||||
global = Option.Boolean('--global,-g', false, {
|
||||
description: 'Create in ~/.claude/agents/ instead of .claude/agents/',
|
||||
});
|
||||
|
||||
output = Option.String('--output,-o', {
|
||||
description: 'Custom output filename (without .md)',
|
||||
});
|
||||
|
||||
dryRun = Option.Boolean('--dry-run,-n', false, {
|
||||
description: 'Preview without writing files',
|
||||
});
|
||||
|
||||
async execute(): Promise<number> {
|
||||
const skills = discoverSkills(process.cwd());
|
||||
const skill = skills.find((s: Skill) => s.name === this.skillName);
|
||||
|
||||
if (!skill) {
|
||||
console.log(chalk.red(`Skill not found: ${this.skillName}`));
|
||||
console.log(chalk.dim('Available skills:'));
|
||||
for (const s of skills.slice(0, 10)) {
|
||||
console.log(chalk.dim(` - ${s.name}`));
|
||||
}
|
||||
if (skills.length > 10) {
|
||||
console.log(chalk.dim(` ... and ${skills.length - 10} more`));
|
||||
}
|
||||
return 1;
|
||||
}
|
||||
|
||||
const skillContent = readSkillContent(skill.path);
|
||||
if (!skillContent) {
|
||||
console.log(chalk.red(`Could not read skill content: ${skill.path}`));
|
||||
return 1;
|
||||
}
|
||||
|
||||
const options: SkillToSubagentOptions = {
|
||||
inline: this.inline,
|
||||
};
|
||||
|
||||
if (this.model) {
|
||||
const validModels = ['sonnet', 'opus', 'haiku', 'inherit'];
|
||||
if (!validModels.includes(this.model)) {
|
||||
console.log(chalk.red(`Invalid model: ${this.model}`));
|
||||
console.log(chalk.dim(`Valid options: ${validModels.join(', ')}`));
|
||||
return 1;
|
||||
}
|
||||
options.model = this.model as 'sonnet' | 'opus' | 'haiku' | 'inherit';
|
||||
}
|
||||
|
||||
if (this.permission) {
|
||||
const validModes = ['default', 'plan', 'auto-edit', 'full-auto', 'bypassPermissions'];
|
||||
if (!validModes.includes(this.permission)) {
|
||||
console.log(chalk.red(`Invalid permission mode: ${this.permission}`));
|
||||
console.log(chalk.dim(`Valid options: ${validModes.join(', ')}`));
|
||||
return 1;
|
||||
}
|
||||
options.permissionMode = this.permission as AgentPermissionMode;
|
||||
}
|
||||
|
||||
const content = generateSubagentFromSkill(skill, skillContent, options);
|
||||
|
||||
const targetDir = this.global
|
||||
? join(homedir(), '.claude', 'agents')
|
||||
: join(process.cwd(), '.claude', 'agents');
|
||||
|
||||
let filename: string;
|
||||
if (this.output) {
|
||||
const sanitized = sanitizeFilename(this.output);
|
||||
if (!sanitized) {
|
||||
console.log(chalk.red(`Invalid output filename: ${this.output}`));
|
||||
console.log(chalk.dim('Filename must contain only alphanumeric characters, hyphens, and underscores'));
|
||||
return 1;
|
||||
}
|
||||
filename = `${sanitized}.md`;
|
||||
} else {
|
||||
const sanitized = sanitizeFilename(skill.name);
|
||||
if (!sanitized) {
|
||||
console.log(chalk.red(`Invalid skill name for filename: ${skill.name}`));
|
||||
console.log(chalk.dim('Skill name must contain only alphanumeric characters, hyphens, and underscores'));
|
||||
return 1;
|
||||
}
|
||||
filename = `${sanitized}.md`;
|
||||
}
|
||||
|
||||
const outputPath = join(targetDir, filename);
|
||||
|
||||
if (this.dryRun) {
|
||||
console.log(chalk.cyan('Preview (dry run):\n'));
|
||||
console.log(chalk.dim(`Would write to: ${outputPath}`));
|
||||
console.log(chalk.dim('─'.repeat(50)));
|
||||
console.log(content);
|
||||
console.log(chalk.dim('─'.repeat(50)));
|
||||
return 0;
|
||||
}
|
||||
|
||||
if (!existsSync(targetDir)) {
|
||||
mkdirSync(targetDir, { recursive: true });
|
||||
}
|
||||
|
||||
if (existsSync(outputPath)) {
|
||||
console.log(chalk.yellow(`Overwriting existing file: ${outputPath}`));
|
||||
}
|
||||
|
||||
writeFileSync(outputPath, content);
|
||||
|
||||
console.log(chalk.green(`Created subagent: ${outputPath}`));
|
||||
console.log();
|
||||
console.log(chalk.dim(`Invoke with: @${skill.name}`));
|
||||
if (!this.inline) {
|
||||
console.log(chalk.dim(`Skills referenced: ${skill.name}`));
|
||||
} else {
|
||||
console.log(chalk.dim('Skill content embedded inline'));
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
}
|
||||
|
||||
function formatCategoryName(category: string): string {
|
||||
return category
|
||||
.split('-')
|
||||
.map(word => word.charAt(0).toUpperCase() + word.slice(1))
|
||||
.join(' ');
|
||||
}
|
||||
|
||||
function sanitizeFilename(input: string): string | null {
|
||||
const base = basename(input);
|
||||
const stem = base.replace(/\.md$/i, '');
|
||||
|
||||
if (!stem || stem.startsWith('.') || stem.startsWith('-')) {
|
||||
return null;
|
||||
}
|
||||
|
||||
if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(stem)) {
|
||||
return null;
|
||||
}
|
||||
|
||||
if (stem.length > 64) {
|
||||
return null;
|
||||
}
|
||||
|
||||
return stem;
|
||||
}
|
||||
|
||||
@@ -43,12 +43,13 @@ export { PlanCommand } from './plan.js';
|
||||
export { CommandCmd, CommandAvailableCommand, CommandInstallCommand } from './command.js';
|
||||
export { AICommand } from './ai.js';
|
||||
export { AuditCommand } from './audit.js';
|
||||
export { PublishCommand } from './publish.js';
|
||||
export { PublishCommand, PublishSubmitCommand } from './publish.js';
|
||||
export {
|
||||
AgentCommand,
|
||||
AgentListCommand,
|
||||
AgentShowCommand,
|
||||
AgentCreateCommand,
|
||||
AgentFromSkillCommand,
|
||||
AgentTranslateCommand,
|
||||
AgentSyncCommand,
|
||||
AgentValidateCommand,
|
||||
@@ -104,3 +105,6 @@ export {
|
||||
GuidelineCreateCommand,
|
||||
GuidelineRemoveCommand,
|
||||
} from './guideline.js';
|
||||
|
||||
// Tree command for hierarchical skill browsing (Phase 21)
|
||||
export { TreeCommand } from './tree.js';
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
import { existsSync, mkdirSync, cpSync, rmSync, symlinkSync } from 'node:fs';
|
||||
import { join } from 'node:path';
|
||||
import { execFile } from 'node:child_process';
|
||||
import { promisify } from 'node:util';
|
||||
|
||||
const execFileAsync = promisify(execFile);
|
||||
import { Command, Option } from 'clipanion';
|
||||
import { detectProvider, isLocalPath, getProvider, evaluateSkillDirectory } from '@skillkit/core';
|
||||
import type { SkillMetadata, GitProvider, AgentType } from '@skillkit/core';
|
||||
@@ -42,7 +46,8 @@ export class InstallCommand extends Command {
|
||||
['Install from GitHub', '$0 install owner/repo'],
|
||||
['Install from GitLab', '$0 install gitlab:owner/repo'],
|
||||
['Install from Bitbucket', '$0 install bitbucket:owner/repo'],
|
||||
['Install specific skills (CI/CD)', '$0 install owner/repo --skills=pdf,xlsx'],
|
||||
['Install specific skill', '$0 install owner/repo --skill=pdf'],
|
||||
['Install multiple skills (CI/CD)', '$0 install owner/repo --skills=pdf,xlsx'],
|
||||
['Install all skills non-interactively', '$0 install owner/repo --all'],
|
||||
['Install from local path', '$0 install ./my-skills'],
|
||||
['Install globally', '$0 install owner/repo --global'],
|
||||
@@ -53,7 +58,7 @@ export class InstallCommand extends Command {
|
||||
|
||||
source = Option.String({ required: true });
|
||||
|
||||
skills = Option.String('--skills,-s', {
|
||||
skills = Option.String('--skills,--skill,-s', {
|
||||
description: 'Comma-separated list of skills to install (non-interactive)',
|
||||
});
|
||||
|
||||
@@ -143,7 +148,7 @@ export class InstallCommand extends Command {
|
||||
}
|
||||
console.log('');
|
||||
console.log(colors.muted(`Total: ${discoveredSkills.length} skill(s)`));
|
||||
console.log(colors.muted('To install: skillkit install <source> --skills=skill1,skill2'));
|
||||
console.log(colors.muted('To install: skillkit install <source> --skill=name'));
|
||||
}
|
||||
|
||||
const cleanupPath = result.tempRoot || result.path;
|
||||
@@ -334,6 +339,21 @@ export class InstallCommand extends Command {
|
||||
if (isSymlinkMode && primaryPath === null) {
|
||||
primaryPath = targetPath;
|
||||
}
|
||||
|
||||
// Auto-install npm dependencies if package.json exists
|
||||
const packageJsonPath = join(targetPath, 'package.json');
|
||||
if (existsSync(packageJsonPath)) {
|
||||
s.stop(`Installed ${skillName} to ${adapter.name}`);
|
||||
s.start(`Installing npm dependencies for ${skillName}...`);
|
||||
try {
|
||||
await execFileAsync('npm', ['install', '--production'], { cwd: targetPath });
|
||||
s.stop(`Installed dependencies for ${skillName}`);
|
||||
} catch (npmErr) {
|
||||
s.stop(colors.warning(`Dependencies failed for ${skillName}`));
|
||||
console.log(colors.muted('Run manually: npm install in ' + targetPath));
|
||||
}
|
||||
s.start(`Finishing ${skillName} installation...`);
|
||||
}
|
||||
}
|
||||
|
||||
const metadata: SkillMetadata = {
|
||||
|
||||
@@ -1,8 +1,20 @@
|
||||
import { existsSync, readFileSync } from 'node:fs';
|
||||
import { join, basename, dirname } from 'node:path';
|
||||
import { execSync } from 'node:child_process';
|
||||
import { existsSync, readFileSync, mkdirSync, writeFileSync, readdirSync, statSync } from 'node:fs';
|
||||
import { join, basename, dirname, resolve } from 'node:path';
|
||||
import chalk from 'chalk';
|
||||
import { Command, Option } from 'clipanion';
|
||||
import { generateWellKnownIndex, type WellKnownSkill } from '@skillkit/core';
|
||||
|
||||
function sanitizeSkillName(name: string): string | null {
|
||||
if (!name || typeof name !== 'string') return null;
|
||||
const base = basename(name);
|
||||
if (base !== name || name.includes('..') || name.includes('/') || name.includes('\\')) {
|
||||
return null;
|
||||
}
|
||||
if (!/^[a-zA-Z0-9._-]+$/.test(name)) {
|
||||
return null;
|
||||
}
|
||||
return name;
|
||||
}
|
||||
|
||||
interface SkillFrontmatter {
|
||||
name?: string;
|
||||
@@ -15,141 +27,201 @@ export class PublishCommand extends Command {
|
||||
static override paths = [['publish']];
|
||||
|
||||
static override usage = Command.Usage({
|
||||
description: 'Publish your skill to the SkillKit marketplace',
|
||||
description: 'Generate well-known skills structure for hosting',
|
||||
details: `
|
||||
This command generates the RFC 8615 well-known URI structure for hosting skills.
|
||||
|
||||
The output includes:
|
||||
- .well-known/skills/index.json - Skill manifest for auto-discovery
|
||||
- .well-known/skills/{skill-name}/SKILL.md - Individual skill files
|
||||
|
||||
Users can then install skills via: skillkit add https://your-domain.com
|
||||
`,
|
||||
examples: [
|
||||
['Publish skill from current directory', '$0 publish'],
|
||||
['Publish skill from specific path', '$0 publish ./my-skill'],
|
||||
['Publish with custom name', '$0 publish --name my-awesome-skill'],
|
||||
['Generate from current directory', '$0 publish'],
|
||||
['Generate from specific path', '$0 publish ./my-skills'],
|
||||
['Generate to custom output directory', '$0 publish --output ./public'],
|
||||
['Preview without writing', '$0 publish --dry-run'],
|
||||
],
|
||||
});
|
||||
|
||||
skillPath = Option.String({ required: false, name: 'path' });
|
||||
|
||||
name = Option.String('--name,-n', {
|
||||
description: 'Custom skill name (default: parsed from SKILL.md)',
|
||||
output = Option.String('--output,-o', {
|
||||
description: 'Output directory for well-known structure (default: current directory)',
|
||||
});
|
||||
|
||||
dryRun = Option.Boolean('--dry-run', false, {
|
||||
description: 'Show what would be published without actually publishing',
|
||||
dryRun = Option.Boolean('--dry-run,-n', false, {
|
||||
description: 'Show what would be generated without writing files',
|
||||
});
|
||||
|
||||
async execute(): Promise<number> {
|
||||
const skillPath = this.skillPath || process.cwd();
|
||||
const skillMdPath = this.findSkillMd(skillPath);
|
||||
const basePath = this.skillPath || process.cwd();
|
||||
const outputDir = this.output || basePath;
|
||||
|
||||
if (!skillMdPath) {
|
||||
console.error(chalk.red('No SKILL.md found'));
|
||||
console.error(chalk.dim('Run this command from a directory containing SKILL.md'));
|
||||
console.error(chalk.dim('Or specify the path: skillkit publish ./path/to/skill'));
|
||||
console.log(chalk.cyan('Generating well-known skills structure...\n'));
|
||||
|
||||
const discoveredSkills = this.discoverSkills(basePath);
|
||||
|
||||
if (discoveredSkills.length === 0) {
|
||||
console.error(chalk.red('No skills found'));
|
||||
console.error(chalk.dim('Skills must contain a SKILL.md file with frontmatter'));
|
||||
return 1;
|
||||
}
|
||||
|
||||
console.log(chalk.cyan('Publishing skill to SkillKit marketplace...\n'));
|
||||
console.log(chalk.white(`Found ${discoveredSkills.length} skill(s):\n`));
|
||||
|
||||
// Parse SKILL.md
|
||||
const content = readFileSync(skillMdPath, 'utf-8');
|
||||
const frontmatter = this.parseFrontmatter(content);
|
||||
const skillName = this.name || frontmatter.name || basename(dirname(skillMdPath));
|
||||
const wellKnownSkills: WellKnownSkill[] = [];
|
||||
|
||||
// Get git repo info
|
||||
const repoInfo = this.getRepoInfo(dirname(skillMdPath));
|
||||
if (!repoInfo) {
|
||||
console.error(chalk.red('Not a git repository or no remote configured'));
|
||||
console.error(chalk.dim('Your skill must be in a git repository with a GitHub remote'));
|
||||
const validSkills: Array<{ name: string; safeName: string; description?: string; path: string }> = [];
|
||||
|
||||
for (const skill of discoveredSkills) {
|
||||
const safeName = sanitizeSkillName(skill.name);
|
||||
if (!safeName) {
|
||||
console.log(chalk.yellow(` ${chalk.yellow('⚠')} Skipping "${skill.name}" (invalid name - must be alphanumeric with hyphens/underscores)`));
|
||||
continue;
|
||||
}
|
||||
|
||||
const files = this.getSkillFiles(skill.path);
|
||||
console.log(chalk.dim(` ${chalk.green('●')} ${safeName}`));
|
||||
console.log(chalk.dim(` Description: ${skill.description || 'No description'}`));
|
||||
console.log(chalk.dim(` Files: ${files.join(', ')}`));
|
||||
|
||||
validSkills.push({ name: skill.name, safeName, description: skill.description, path: skill.path });
|
||||
wellKnownSkills.push({
|
||||
name: safeName,
|
||||
description: skill.description,
|
||||
files,
|
||||
});
|
||||
}
|
||||
|
||||
if (validSkills.length === 0) {
|
||||
console.error(chalk.red('\nNo valid skills to publish'));
|
||||
return 1;
|
||||
}
|
||||
|
||||
// Build skill entry
|
||||
const skillSlug = this.slugify(skillName);
|
||||
if (!skillSlug) {
|
||||
console.error(chalk.red('Skill name produces an empty slug.'));
|
||||
console.error(chalk.dim('Please pass --name with letters or numbers.'));
|
||||
return 1;
|
||||
}
|
||||
const skillEntry = {
|
||||
id: `${repoInfo.owner}/${repoInfo.repo}/${skillSlug}`,
|
||||
name: this.formatName(skillName),
|
||||
description: frontmatter.description || `Best practices and patterns for ${this.formatName(skillName)}`,
|
||||
source: `${repoInfo.owner}/${repoInfo.repo}`,
|
||||
tags: frontmatter.tags || this.inferTags(skillName, frontmatter.description || ''),
|
||||
};
|
||||
|
||||
console.log(chalk.white('Skill details:'));
|
||||
console.log(chalk.dim(` ID: ${skillEntry.id}`));
|
||||
console.log(chalk.dim(` Name: ${skillEntry.name}`));
|
||||
console.log(chalk.dim(` Description: ${skillEntry.description}`));
|
||||
console.log(chalk.dim(` Source: ${skillEntry.source}`));
|
||||
console.log(chalk.dim(` Tags: ${skillEntry.tags.join(', ')}`));
|
||||
console.log();
|
||||
console.log('');
|
||||
|
||||
if (this.dryRun) {
|
||||
console.log(chalk.yellow('Dry run - not publishing'));
|
||||
console.log(chalk.dim('JSON entry that would be added:'));
|
||||
console.log(JSON.stringify(skillEntry, null, 2));
|
||||
console.log(chalk.yellow('Dry run - not writing files\n'));
|
||||
console.log(chalk.white('Would generate:'));
|
||||
console.log(chalk.dim(` ${outputDir}/.well-known/skills/index.json`));
|
||||
for (const skill of wellKnownSkills) {
|
||||
for (const file of skill.files) {
|
||||
console.log(chalk.dim(` ${outputDir}/.well-known/skills/${skill.name}/${file}`));
|
||||
}
|
||||
}
|
||||
console.log('');
|
||||
console.log(chalk.white('index.json preview:'));
|
||||
console.log(JSON.stringify(generateWellKnownIndex(wellKnownSkills), null, 2));
|
||||
return 0;
|
||||
}
|
||||
|
||||
// Create GitHub issue to add skill
|
||||
const issueBody = this.createIssueBody(skillEntry);
|
||||
const issueTitle = encodeURIComponent(`[Publish] ${skillEntry.name}`);
|
||||
const issueBodyEncoded = encodeURIComponent(issueBody);
|
||||
const issueUrl = `https://github.com/rohitg00/skillkit/issues/new?title=${issueTitle}&body=${issueBodyEncoded}&labels=skill-submission,publish`;
|
||||
const wellKnownDir = join(outputDir, '.well-known', 'skills');
|
||||
mkdirSync(wellKnownDir, { recursive: true });
|
||||
|
||||
console.log(chalk.green('Opening GitHub to submit your skill...\n'));
|
||||
for (const skill of validSkills) {
|
||||
const skillDir = join(wellKnownDir, skill.safeName);
|
||||
const resolvedSkillDir = resolve(skillDir);
|
||||
const resolvedWellKnownDir = resolve(wellKnownDir);
|
||||
|
||||
try {
|
||||
// Try to open the URL
|
||||
const openCmd =
|
||||
process.platform === 'darwin'
|
||||
? `open "${issueUrl}"`
|
||||
: process.platform === 'win32'
|
||||
? `cmd /c start "" "${issueUrl}"`
|
||||
: `xdg-open "${issueUrl}"`;
|
||||
execSync(openCmd, { stdio: 'ignore' });
|
||||
if (!resolvedSkillDir.startsWith(resolvedWellKnownDir)) {
|
||||
console.log(chalk.yellow(` Skipping "${skill.name}" (path traversal detected)`));
|
||||
continue;
|
||||
}
|
||||
|
||||
console.log(chalk.green('GitHub issue page opened!'));
|
||||
console.log(chalk.dim('Review and submit the issue to publish your skill.'));
|
||||
} catch {
|
||||
console.log(chalk.yellow('Could not open browser automatically.'));
|
||||
console.log(chalk.dim('Please open this URL manually:\n'));
|
||||
console.log(chalk.cyan(issueUrl));
|
||||
mkdirSync(skillDir, { recursive: true });
|
||||
|
||||
const files = this.getSkillFiles(skill.path);
|
||||
for (const file of files) {
|
||||
const safeFile = basename(file);
|
||||
const sourcePath = join(skill.path, file);
|
||||
const destPath = join(skillDir, safeFile);
|
||||
const content = readFileSync(sourcePath, 'utf-8');
|
||||
writeFileSync(destPath, content);
|
||||
}
|
||||
}
|
||||
|
||||
console.log();
|
||||
const index = generateWellKnownIndex(wellKnownSkills);
|
||||
writeFileSync(join(wellKnownDir, 'index.json'), JSON.stringify(index, null, 2));
|
||||
|
||||
console.log(chalk.green('Generated well-known structure:\n'));
|
||||
console.log(chalk.dim(` ${wellKnownDir}/index.json`));
|
||||
for (const skill of wellKnownSkills) {
|
||||
console.log(chalk.dim(` ${wellKnownDir}/${skill.name}/`));
|
||||
}
|
||||
|
||||
console.log('');
|
||||
console.log(chalk.cyan('Next steps:'));
|
||||
console.log(chalk.dim(' 1. Review the skill details in the GitHub issue'));
|
||||
console.log(chalk.dim(' 2. Submit the issue'));
|
||||
console.log(chalk.dim(' 3. A maintainer will review and add your skill'));
|
||||
console.log(chalk.dim(' 1. Deploy the .well-known directory to your web server'));
|
||||
console.log(chalk.dim(' 2. Users can install via: skillkit add https://your-domain.com'));
|
||||
console.log(chalk.dim(' 3. Skills auto-discovered from /.well-known/skills/index.json'));
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
private findSkillMd(basePath: string): string | null {
|
||||
// Check if path is directly to SKILL.md
|
||||
if (basePath.endsWith('SKILL.md') && existsSync(basePath)) {
|
||||
return basePath;
|
||||
private discoverSkills(basePath: string): Array<{ name: string; description?: string; path: string }> {
|
||||
const skills: Array<{ name: string; description?: string; path: string }> = [];
|
||||
|
||||
const skillMdPath = join(basePath, 'SKILL.md');
|
||||
if (existsSync(skillMdPath)) {
|
||||
const content = readFileSync(skillMdPath, 'utf-8');
|
||||
const frontmatter = this.parseFrontmatter(content);
|
||||
skills.push({
|
||||
name: frontmatter.name || basename(basePath),
|
||||
description: frontmatter.description,
|
||||
path: basePath,
|
||||
});
|
||||
return skills;
|
||||
}
|
||||
|
||||
// Check if SKILL.md exists in the directory
|
||||
const direct = join(basePath, 'SKILL.md');
|
||||
if (existsSync(direct)) {
|
||||
return direct;
|
||||
}
|
||||
|
||||
// Check common skill locations
|
||||
const locations = [
|
||||
join(basePath, 'skills', 'SKILL.md'),
|
||||
join(basePath, '.claude', 'skills', 'SKILL.md'),
|
||||
join(basePath, '.cursor', 'skills', 'SKILL.md'),
|
||||
const searchDirs = [
|
||||
basePath,
|
||||
join(basePath, 'skills'),
|
||||
join(basePath, '.claude', 'skills'),
|
||||
];
|
||||
|
||||
for (const loc of locations) {
|
||||
if (existsSync(loc)) {
|
||||
return loc;
|
||||
for (const searchDir of searchDirs) {
|
||||
if (!existsSync(searchDir)) continue;
|
||||
|
||||
const entries = readdirSync(searchDir);
|
||||
for (const entry of entries) {
|
||||
const entryPath = join(searchDir, entry);
|
||||
if (!statSync(entryPath).isDirectory()) continue;
|
||||
|
||||
const entrySkillMd = join(entryPath, 'SKILL.md');
|
||||
if (existsSync(entrySkillMd)) {
|
||||
const content = readFileSync(entrySkillMd, 'utf-8');
|
||||
const frontmatter = this.parseFrontmatter(content);
|
||||
skills.push({
|
||||
name: frontmatter.name || entry,
|
||||
description: frontmatter.description,
|
||||
path: entryPath,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return null;
|
||||
return skills;
|
||||
}
|
||||
|
||||
private getSkillFiles(skillPath: string): string[] {
|
||||
const files: string[] = [];
|
||||
|
||||
const entries = readdirSync(skillPath);
|
||||
for (const entry of entries) {
|
||||
const entryPath = join(skillPath, entry);
|
||||
if (statSync(entryPath).isFile()) {
|
||||
if (entry.startsWith('.') || entry === '.skillkit-metadata.json') continue;
|
||||
files.push(entry);
|
||||
}
|
||||
}
|
||||
|
||||
if (!files.includes('SKILL.md')) {
|
||||
files.unshift('SKILL.md');
|
||||
}
|
||||
|
||||
return files;
|
||||
}
|
||||
|
||||
private parseFrontmatter(content: string): SkillFrontmatter {
|
||||
@@ -161,7 +233,6 @@ export class PublishCommand extends Command {
|
||||
let inTagsList = false;
|
||||
|
||||
for (const line of lines) {
|
||||
// Handle multiline tags list
|
||||
if (inTagsList) {
|
||||
const tagMatch = line.match(/^\s*-\s*(.+)$/);
|
||||
if (tagMatch) {
|
||||
@@ -190,7 +261,6 @@ export class PublishCommand extends Command {
|
||||
frontmatter.version = value.replace(/^["']|["']$/g, '');
|
||||
break;
|
||||
case 'tags':
|
||||
// Parse YAML array: [tag1, tag2] or multiline list
|
||||
if (value.startsWith('[')) {
|
||||
frontmatter.tags = value
|
||||
.slice(1, -1)
|
||||
@@ -207,6 +277,171 @@ export class PublishCommand extends Command {
|
||||
|
||||
return frontmatter;
|
||||
}
|
||||
}
|
||||
|
||||
export class PublishSubmitCommand extends Command {
|
||||
static override paths = [['publish', 'submit']];
|
||||
|
||||
static override usage = Command.Usage({
|
||||
description: 'Submit skill to SkillKit marketplace (requires review)',
|
||||
examples: [
|
||||
['Submit skill from current directory', '$0 publish submit'],
|
||||
['Submit with custom name', '$0 publish submit --name my-skill'],
|
||||
],
|
||||
});
|
||||
|
||||
skillPath = Option.String({ required: false, name: 'path' });
|
||||
|
||||
name = Option.String('--name,-n', {
|
||||
description: 'Custom skill name',
|
||||
});
|
||||
|
||||
dryRun = Option.Boolean('--dry-run', false, {
|
||||
description: 'Show what would be submitted',
|
||||
});
|
||||
|
||||
async execute(): Promise<number> {
|
||||
const skillPath = this.skillPath || process.cwd();
|
||||
const skillMdPath = this.findSkillMd(skillPath);
|
||||
|
||||
if (!skillMdPath) {
|
||||
console.error(chalk.red('No SKILL.md found'));
|
||||
console.error(chalk.dim('Run this command from a directory containing SKILL.md'));
|
||||
return 1;
|
||||
}
|
||||
|
||||
console.log(chalk.cyan('Submitting skill to SkillKit marketplace...\n'));
|
||||
|
||||
const content = readFileSync(skillMdPath, 'utf-8');
|
||||
const frontmatter = this.parseFrontmatter(content);
|
||||
const skillName = this.name || frontmatter.name || basename(dirname(skillMdPath));
|
||||
|
||||
const repoInfo = this.getRepoInfo(dirname(skillMdPath));
|
||||
if (!repoInfo) {
|
||||
console.error(chalk.red('Not a git repository or no remote configured'));
|
||||
console.error(chalk.dim('Your skill must be in a git repository with a GitHub remote'));
|
||||
return 1;
|
||||
}
|
||||
|
||||
const skillSlug = this.slugify(skillName);
|
||||
if (!skillSlug) {
|
||||
console.error(chalk.red('Skill name produces an empty slug.'));
|
||||
console.error(chalk.dim('Please pass --name with letters or numbers.'));
|
||||
return 1;
|
||||
}
|
||||
|
||||
const skillEntry = {
|
||||
id: `${repoInfo.owner}/${repoInfo.repo}/${skillSlug}`,
|
||||
name: this.formatName(skillName),
|
||||
description: frontmatter.description || `Best practices for ${this.formatName(skillName)}`,
|
||||
source: `${repoInfo.owner}/${repoInfo.repo}`,
|
||||
tags: frontmatter.tags || ['general'],
|
||||
};
|
||||
|
||||
console.log(chalk.white('Skill details:'));
|
||||
console.log(chalk.dim(` ID: ${skillEntry.id}`));
|
||||
console.log(chalk.dim(` Name: ${skillEntry.name}`));
|
||||
console.log(chalk.dim(` Description: ${skillEntry.description}`));
|
||||
console.log(chalk.dim(` Source: ${skillEntry.source}`));
|
||||
console.log(chalk.dim(` Tags: ${skillEntry.tags.join(', ')}`));
|
||||
console.log();
|
||||
|
||||
if (this.dryRun) {
|
||||
console.log(chalk.yellow('Dry run - not submitting'));
|
||||
console.log(JSON.stringify(skillEntry, null, 2));
|
||||
return 0;
|
||||
}
|
||||
|
||||
const issueBody = this.createIssueBody(skillEntry);
|
||||
const issueTitle = encodeURIComponent(`[Publish] ${skillEntry.name}`);
|
||||
const issueBodyEncoded = encodeURIComponent(issueBody);
|
||||
const issueUrl = `https://github.com/rohitg00/skillkit/issues/new?title=${issueTitle}&body=${issueBodyEncoded}&labels=skill-submission,publish`;
|
||||
|
||||
console.log(chalk.green('Opening GitHub to submit your skill...\n'));
|
||||
|
||||
try {
|
||||
const { execSync } = await import('node:child_process');
|
||||
const openCmd =
|
||||
process.platform === 'darwin'
|
||||
? `open "${issueUrl}"`
|
||||
: process.platform === 'win32'
|
||||
? `cmd /c start "" "${issueUrl}"`
|
||||
: `xdg-open "${issueUrl}"`;
|
||||
execSync(openCmd, { stdio: 'ignore' });
|
||||
|
||||
console.log(chalk.green('GitHub issue page opened!'));
|
||||
console.log(chalk.dim('Review and submit the issue.'));
|
||||
} catch {
|
||||
console.log(chalk.yellow('Could not open browser automatically.'));
|
||||
console.log(chalk.dim('Please open this URL manually:\n'));
|
||||
console.log(chalk.cyan(issueUrl));
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
private findSkillMd(basePath: string): string | null {
|
||||
if (basePath.endsWith('SKILL.md') && existsSync(basePath)) {
|
||||
return basePath;
|
||||
}
|
||||
|
||||
const direct = join(basePath, 'SKILL.md');
|
||||
if (existsSync(direct)) {
|
||||
return direct;
|
||||
}
|
||||
|
||||
const locations = [
|
||||
join(basePath, 'skills', 'SKILL.md'),
|
||||
join(basePath, '.claude', 'skills', 'SKILL.md'),
|
||||
];
|
||||
|
||||
for (const loc of locations) {
|
||||
if (existsSync(loc)) {
|
||||
return loc;
|
||||
}
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
private parseFrontmatter(content: string): SkillFrontmatter {
|
||||
const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
|
||||
if (!match) return {};
|
||||
|
||||
const frontmatter: SkillFrontmatter = {};
|
||||
const lines = match[1].split(/\r?\n/);
|
||||
|
||||
for (const line of lines) {
|
||||
const colonIdx = line.indexOf(':');
|
||||
if (colonIdx === -1) continue;
|
||||
|
||||
const key = line.slice(0, colonIdx).trim();
|
||||
const value = line.slice(colonIdx + 1).trim();
|
||||
|
||||
switch (key) {
|
||||
case 'name':
|
||||
frontmatter.name = value.replace(/^["']|["']$/g, '');
|
||||
break;
|
||||
case 'description':
|
||||
frontmatter.description = value.replace(/^["']|["']$/g, '');
|
||||
break;
|
||||
case 'version':
|
||||
frontmatter.version = value.replace(/^["']|["']$/g, '');
|
||||
break;
|
||||
case 'tags':
|
||||
if (value.startsWith('[')) {
|
||||
frontmatter.tags = value
|
||||
.slice(1, -1)
|
||||
.split(',')
|
||||
.map(t => t.trim().replace(/^["']|["']$/g, ''))
|
||||
.filter(t => t.length > 0);
|
||||
}
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
return frontmatter;
|
||||
}
|
||||
|
||||
private slugify(name: string): string {
|
||||
return name
|
||||
@@ -218,19 +453,19 @@ export class PublishCommand extends Command {
|
||||
|
||||
private getRepoInfo(dir: string): { owner: string; repo: string } | null {
|
||||
try {
|
||||
const { execSync } = require('node:child_process');
|
||||
const remote = execSync('git remote get-url origin', {
|
||||
cwd: dir,
|
||||
encoding: 'utf-8',
|
||||
stdio: ['pipe', 'pipe', 'ignore'],
|
||||
}).trim();
|
||||
|
||||
// Parse GitHub URL: git@github.com:owner/repo.git or https://github.com/owner/repo.git
|
||||
const match = remote.match(/github\.com[:/]([^/]+)\/(.+?)(?:\.git)?$/);
|
||||
if (match) {
|
||||
return { owner: match[1], repo: match[2] };
|
||||
}
|
||||
} catch {
|
||||
// Not a git repo or no remote
|
||||
// Not a git repo
|
||||
}
|
||||
|
||||
return null;
|
||||
@@ -243,31 +478,6 @@ export class PublishCommand extends Command {
|
||||
.join(' ');
|
||||
}
|
||||
|
||||
private inferTags(name: string, description: string): string[] {
|
||||
const tags: string[] = [];
|
||||
const text = `${name} ${description}`.toLowerCase();
|
||||
|
||||
const tagMap: Record<string, string[]> = {
|
||||
react: ['react', 'jsx', 'tsx'],
|
||||
typescript: ['typescript', 'ts'],
|
||||
nextjs: ['next', 'nextjs'],
|
||||
testing: ['test', 'jest', 'vitest'],
|
||||
mobile: ['mobile', 'react-native', 'expo'],
|
||||
backend: ['backend', 'api', 'server'],
|
||||
database: ['database', 'postgres', 'mysql', 'supabase'],
|
||||
frontend: ['frontend', 'ui', 'design'],
|
||||
devops: ['devops', 'ci', 'cd', 'docker'],
|
||||
};
|
||||
|
||||
for (const [tag, keywords] of Object.entries(tagMap)) {
|
||||
if (keywords.some(k => text.includes(k))) {
|
||||
tags.push(tag);
|
||||
}
|
||||
}
|
||||
|
||||
return tags.length > 0 ? tags : ['general'];
|
||||
}
|
||||
|
||||
private createIssueBody(
|
||||
skill: { id: string; name: string; description: string; source: string; tags: string[] }
|
||||
): string {
|
||||
@@ -292,6 +502,6 @@ ${JSON.stringify(skill, null, 2)}
|
||||
- [ ] Tags are appropriate
|
||||
|
||||
---
|
||||
Submitted via \`skillkit publish\``;
|
||||
Submitted via \`skillkit publish submit\``;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -3,8 +3,10 @@ import { resolve } from 'node:path';
|
||||
import {
|
||||
type ProjectProfile,
|
||||
type ScoredSkill,
|
||||
type ExplainedScoredSkill,
|
||||
ContextManager,
|
||||
RecommendationEngine,
|
||||
ReasoningRecommendationEngine,
|
||||
buildSkillIndex,
|
||||
saveIndex,
|
||||
loadIndex as loadIndexFromCache,
|
||||
@@ -50,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'],
|
||||
],
|
||||
});
|
||||
|
||||
@@ -108,6 +113,41 @@ export class RecommendCommand extends Command {
|
||||
description: 'Minimal output',
|
||||
});
|
||||
|
||||
// Explain mode (reasoning-based recommendations)
|
||||
explain = Option.Boolean('--explain,-e', false, {
|
||||
description: 'Show detailed explanations for recommendations (uses reasoning engine)',
|
||||
});
|
||||
|
||||
// Reasoning mode
|
||||
reasoning = Option.Boolean('--reasoning,-r', false, {
|
||||
description: 'Use LLM-based reasoning for recommendations',
|
||||
});
|
||||
|
||||
// Show tree path
|
||||
showPath = Option.Boolean('--show-path', false, {
|
||||
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());
|
||||
|
||||
@@ -116,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');
|
||||
}
|
||||
@@ -139,6 +189,11 @@ export class RecommendCommand extends Command {
|
||||
return 0;
|
||||
}
|
||||
|
||||
// Use reasoning engine if explain/reasoning flags are set
|
||||
if (this.explain || this.reasoning || this.showPath) {
|
||||
return await this.handleReasoningRecommendations(profile, index);
|
||||
}
|
||||
|
||||
// Create recommendation engine
|
||||
const engine = new RecommendationEngine();
|
||||
engine.loadIndex(index);
|
||||
@@ -146,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);
|
||||
}
|
||||
|
||||
@@ -168,6 +226,63 @@ export class RecommendCommand extends Command {
|
||||
return 0;
|
||||
}
|
||||
|
||||
private async handleReasoningRecommendations(
|
||||
profile: ProjectProfile,
|
||||
index: { skills: ScoredSkill['skill'][]; sources: { name: string; url: string; lastFetched: string; skillCount: number }[]; version: number; lastUpdated: string }
|
||||
): Promise<number> {
|
||||
const s = !this.quiet && !this.json ? spinner() : null;
|
||||
s?.start('Analyzing with reasoning engine...');
|
||||
|
||||
try {
|
||||
const engine = new ReasoningRecommendationEngine();
|
||||
engine.loadIndex(index);
|
||||
await engine.initReasoning();
|
||||
|
||||
const result = await engine.recommendWithReasoning(profile, {
|
||||
limit: this.limit ? parseInt(this.limit, 10) : 10,
|
||||
minScore: this.minScore ? parseInt(this.minScore, 10) : 30,
|
||||
categories: this.category,
|
||||
excludeInstalled: !this.includeInstalled,
|
||||
includeReasons: this.verbose,
|
||||
reasoning: this.reasoning,
|
||||
explainResults: this.explain,
|
||||
useTree: true,
|
||||
});
|
||||
|
||||
s?.stop('Analysis complete');
|
||||
|
||||
if (this.json) {
|
||||
console.log(JSON.stringify(result, null, 2));
|
||||
return 0;
|
||||
}
|
||||
|
||||
this.displayExplainedRecommendations(
|
||||
result.recommendations,
|
||||
profile,
|
||||
result.totalSkillsScanned,
|
||||
result.reasoningSummary
|
||||
);
|
||||
return 0;
|
||||
} catch (err) {
|
||||
s?.stop(colors.error('Reasoning analysis failed'));
|
||||
console.log(colors.muted(err instanceof Error ? err.message : String(err)));
|
||||
console.log(colors.muted('Falling back to standard recommendations...'));
|
||||
console.log('');
|
||||
|
||||
const engine = new RecommendationEngine();
|
||||
engine.loadIndex(index);
|
||||
const result = engine.recommend(profile, {
|
||||
limit: this.limit ? parseInt(this.limit, 10) : 10,
|
||||
minScore: this.minScore ? parseInt(this.minScore, 10) : 30,
|
||||
categories: this.category,
|
||||
excludeInstalled: !this.includeInstalled,
|
||||
includeReasons: this.verbose,
|
||||
});
|
||||
this.displayRecommendations(result.recommendations, profile, result.totalSkillsScanned);
|
||||
return 0;
|
||||
}
|
||||
}
|
||||
|
||||
private async getProjectProfile(projectPath: string): Promise<ProjectProfile | null> {
|
||||
const manager = new ContextManager(projectPath);
|
||||
let context = manager.get();
|
||||
@@ -276,6 +391,223 @@ export class RecommendCommand extends Command {
|
||||
console.log(colors.muted('Install with: skillkit install <source>'));
|
||||
}
|
||||
|
||||
private displayExplainedRecommendations(
|
||||
recommendations: ExplainedScoredSkill[],
|
||||
profile: ProjectProfile,
|
||||
totalScanned: number,
|
||||
reasoningSummary?: string
|
||||
): void {
|
||||
this.showProjectProfile(profile);
|
||||
|
||||
if (reasoningSummary && !this.quiet) {
|
||||
console.log(colors.dim('Reasoning: ') + colors.muted(reasoningSummary));
|
||||
console.log('');
|
||||
}
|
||||
|
||||
if (recommendations.length === 0) {
|
||||
warn('No matching skills found.');
|
||||
console.log(colors.muted('Try lowering the minimum score with --min-score'));
|
||||
return;
|
||||
}
|
||||
|
||||
console.log(colors.bold(`Explained Recommendations (${recommendations.length} of ${totalScanned} scanned):`));
|
||||
console.log('');
|
||||
|
||||
for (const rec of recommendations) {
|
||||
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 = qualityScore !== null && qualityScore !== undefined
|
||||
? ` ${formatQualityBadge(qualityScore)}`
|
||||
: '';
|
||||
|
||||
console.log(` ${scoreColor(`${rec.score}%`)} ${colors.dim(scoreBar)} ${colors.bold(rec.skill.name)}${qualityDisplay}`);
|
||||
|
||||
if (this.showPath && rec.treePath && rec.treePath.length > 0) {
|
||||
console.log(` ${colors.accent('Path:')} ${rec.treePath.join(' > ')}`);
|
||||
}
|
||||
|
||||
if (rec.skill.description) {
|
||||
console.log(` ${colors.muted(truncate(rec.skill.description, 70))}`);
|
||||
}
|
||||
|
||||
if (rec.skill.source) {
|
||||
console.log(` ${colors.dim('Source:')} ${rec.skill.source}`);
|
||||
}
|
||||
|
||||
if (this.explain && rec.explanation) {
|
||||
console.log(colors.dim(' Why this skill:'));
|
||||
if (rec.explanation.matchedBecause.length > 0) {
|
||||
console.log(` ${colors.success('├─')} Matched: ${rec.explanation.matchedBecause.join(', ')}`);
|
||||
}
|
||||
if (rec.explanation.relevantFor.length > 0) {
|
||||
console.log(` ${colors.accent('├─')} Relevant for: ${rec.explanation.relevantFor.join(', ')}`);
|
||||
}
|
||||
if (rec.explanation.confidence) {
|
||||
const confidenceColor = rec.explanation.confidence === 'high' ? colors.success :
|
||||
rec.explanation.confidence === 'medium' ? colors.warning :
|
||||
colors.muted;
|
||||
console.log(` ${colors.dim('└─')} Confidence: ${confidenceColor(rec.explanation.confidence)}`);
|
||||
}
|
||||
}
|
||||
|
||||
if (this.verbose && rec.reasons.length > 0) {
|
||||
console.log(colors.dim(' Score breakdown:'));
|
||||
for (const reason of rec.reasons.filter(r => r.weight > 0)) {
|
||||
console.log(` ${colors.muted(symbols.stepActive)} ${reason.description} (+${reason.weight})`);
|
||||
}
|
||||
if (qualityScore !== null && qualityScore !== undefined) {
|
||||
const grade = getQualityGradeFromScore(qualityScore);
|
||||
console.log(` ${colors.muted(symbols.stepActive)} Quality: ${qualityScore}/100 (${grade})`);
|
||||
}
|
||||
}
|
||||
|
||||
if (rec.warnings.length > 0) {
|
||||
for (const warning of rec.warnings) {
|
||||
console.log(` ${colors.warning(symbols.warning)} ${warning}`);
|
||||
}
|
||||
}
|
||||
|
||||
console.log('');
|
||||
}
|
||||
|
||||
console.log(colors.muted('Install with: skillkit install <source>'));
|
||||
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}"`);
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
|
||||
import { dirname } from 'node:path';
|
||||
import { Command, Option } from 'clipanion';
|
||||
import { loadConfig, findAllSkills } from '@skillkit/core';
|
||||
import { findAllSkills } from '@skillkit/core';
|
||||
import type { AgentType } from '@skillkit/core';
|
||||
import { getAdapter, detectAgent, getAllAdapters } from '@skillkit/agents';
|
||||
import { getSearchDirs, getAgentConfigPath } from '../helpers.js';
|
||||
@@ -67,10 +67,9 @@ export class SyncCommand extends Command {
|
||||
if (this.agent) {
|
||||
agentType = this.agent as AgentType;
|
||||
} else if (isInteractive) {
|
||||
// Let user select agent
|
||||
// Let user select agent - always detect, don't rely on default config
|
||||
s.start('Detecting agent...');
|
||||
const config = loadConfig();
|
||||
const detected = config.agent || (await detectAgent());
|
||||
const detected = await detectAgent();
|
||||
s.stop(`Detected: ${formatAgent(detected)}`);
|
||||
|
||||
const allAgents = getAllAdapters().map(a => a.type);
|
||||
@@ -92,8 +91,8 @@ export class SyncCommand extends Command {
|
||||
|
||||
agentType = agentResult as AgentType;
|
||||
} else {
|
||||
const config = loadConfig();
|
||||
agentType = config.agent || (await detectAgent());
|
||||
// Non-interactive: always detect, don't rely on default config
|
||||
agentType = await detectAgent();
|
||||
}
|
||||
|
||||
const adapter = getAdapter(agentType);
|
||||
|
||||
@@ -0,0 +1,266 @@
|
||||
import { Command, Option } from 'clipanion';
|
||||
import { join } from 'node:path';
|
||||
import { homedir } from 'node:os';
|
||||
import {
|
||||
loadIndex as loadIndexFromCache,
|
||||
generateSkillTree,
|
||||
saveTree,
|
||||
loadTree,
|
||||
type SkillTree,
|
||||
type TreeNode,
|
||||
} from '@skillkit/core';
|
||||
import {
|
||||
header,
|
||||
colors,
|
||||
symbols,
|
||||
spinner,
|
||||
warn,
|
||||
} from '../onboarding/index.js';
|
||||
|
||||
const TREE_PATH = join(homedir(), '.skillkit', 'skill-tree.json');
|
||||
|
||||
export class TreeCommand extends Command {
|
||||
static override paths = [['tree']];
|
||||
|
||||
static override usage = Command.Usage({
|
||||
description: 'Browse skills in a hierarchical tree structure',
|
||||
details: `
|
||||
The tree command displays skills organized in a hierarchical taxonomy.
|
||||
Navigate through categories like Development, Testing, DevOps, AI/ML, etc.
|
||||
|
||||
Features:
|
||||
- Visual tree structure of all skills
|
||||
- Filter by category path (e.g., "Frontend > React")
|
||||
- Generate tree from skill index
|
||||
- Export to markdown format
|
||||
`,
|
||||
examples: [
|
||||
['Show full tree', '$0 tree'],
|
||||
['Show specific category', '$0 tree Frontend'],
|
||||
['Show subcategory', '$0 tree "Frontend > React"'],
|
||||
['Limit depth', '$0 tree --depth 2'],
|
||||
['Generate/update tree', '$0 tree --generate'],
|
||||
['Export to markdown', '$0 tree --markdown'],
|
||||
['Show tree stats', '$0 tree --stats'],
|
||||
],
|
||||
});
|
||||
|
||||
treePath = Option.String({ required: false });
|
||||
|
||||
depth = Option.String('--depth,-d', {
|
||||
description: 'Maximum depth to display',
|
||||
});
|
||||
|
||||
generate = Option.Boolean('--generate,-g', false, {
|
||||
description: 'Generate/update tree from skill index',
|
||||
});
|
||||
|
||||
markdown = Option.Boolean('--markdown,-m', false, {
|
||||
description: 'Output in markdown format',
|
||||
});
|
||||
|
||||
stats = Option.Boolean('--stats,-s', false, {
|
||||
description: 'Show tree statistics',
|
||||
});
|
||||
|
||||
json = Option.Boolean('--json,-j', false, {
|
||||
description: 'Output in JSON format',
|
||||
});
|
||||
|
||||
quiet = Option.Boolean('--quiet,-q', false, {
|
||||
description: 'Minimal output',
|
||||
});
|
||||
|
||||
async execute(): Promise<number> {
|
||||
if (this.generate) {
|
||||
return await this.generateTree();
|
||||
}
|
||||
|
||||
const tree = this.loadOrGenerateTree();
|
||||
if (!tree) {
|
||||
warn('No skill tree found. Run "skillkit tree --generate" first.');
|
||||
return 1;
|
||||
}
|
||||
|
||||
if (this.stats) {
|
||||
return this.showStats(tree);
|
||||
}
|
||||
|
||||
if (this.json) {
|
||||
console.log(JSON.stringify(tree, null, 2));
|
||||
return 0;
|
||||
}
|
||||
|
||||
if (this.markdown) {
|
||||
const { treeToMarkdown } = await import('@skillkit/core');
|
||||
console.log(treeToMarkdown(tree));
|
||||
return 0;
|
||||
}
|
||||
|
||||
return this.displayTree(tree);
|
||||
}
|
||||
|
||||
private async generateTree(): Promise<number> {
|
||||
if (!this.quiet) {
|
||||
header('Generate Skill Tree');
|
||||
}
|
||||
|
||||
const index = loadIndexFromCache();
|
||||
if (!index || index.skills.length === 0) {
|
||||
warn('No skill index found. Run "skillkit recommend --update" first.');
|
||||
return 1;
|
||||
}
|
||||
|
||||
const s = spinner();
|
||||
s.start('Generating skill tree...');
|
||||
|
||||
try {
|
||||
const tree = generateSkillTree(index.skills);
|
||||
saveTree(tree, TREE_PATH);
|
||||
|
||||
s.stop(`Generated tree with ${tree.totalCategories} categories`);
|
||||
|
||||
console.log('');
|
||||
console.log(colors.success(`${symbols.success} Tree generated successfully`));
|
||||
console.log(colors.muted(` Total skills: ${tree.totalSkills}`));
|
||||
console.log(colors.muted(` Categories: ${tree.totalCategories}`));
|
||||
console.log(colors.muted(` Max depth: ${tree.maxDepth}`));
|
||||
console.log(colors.muted(` Saved to: ${TREE_PATH}`));
|
||||
console.log('');
|
||||
|
||||
return 0;
|
||||
} catch (err) {
|
||||
s.stop(colors.error('Failed to generate tree'));
|
||||
console.log(colors.muted(err instanceof Error ? err.message : String(err)));
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
|
||||
private loadOrGenerateTree(): SkillTree | null {
|
||||
let tree = loadTree(TREE_PATH);
|
||||
|
||||
if (!tree) {
|
||||
const index = loadIndexFromCache();
|
||||
if (index && index.skills.length > 0) {
|
||||
tree = generateSkillTree(index.skills);
|
||||
saveTree(tree, TREE_PATH);
|
||||
}
|
||||
}
|
||||
|
||||
return tree;
|
||||
}
|
||||
|
||||
private showStats(tree: SkillTree): number {
|
||||
if (!this.quiet) {
|
||||
header('Skill Tree Statistics');
|
||||
}
|
||||
|
||||
console.log('');
|
||||
console.log(colors.bold('Overview:'));
|
||||
console.log(` Total Skills: ${colors.accent(String(tree.totalSkills))}`);
|
||||
console.log(` Categories: ${colors.accent(String(tree.totalCategories))}`);
|
||||
console.log(` Max Depth: ${colors.accent(String(tree.maxDepth))}`);
|
||||
console.log(` Generated: ${colors.muted(tree.generatedAt)}`);
|
||||
console.log('');
|
||||
|
||||
console.log(colors.bold('Top-Level Categories:'));
|
||||
for (const child of tree.rootNode.children) {
|
||||
const percentage = tree.totalSkills > 0
|
||||
? ((child.skillCount / tree.totalSkills) * 100).toFixed(1)
|
||||
: '0.0';
|
||||
console.log(
|
||||
` ${colors.accent(child.name.padEnd(15))} ${String(child.skillCount).padStart(6)} skills (${percentage}%)`
|
||||
);
|
||||
|
||||
if (child.children.length > 0) {
|
||||
const subcats = child.children
|
||||
.sort((a, b) => b.skillCount - a.skillCount)
|
||||
.slice(0, 3)
|
||||
.map((c) => `${c.name} (${c.skillCount})`)
|
||||
.join(', ');
|
||||
console.log(` ${colors.muted(subcats)}`);
|
||||
}
|
||||
}
|
||||
console.log('');
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
private displayTree(tree: SkillTree): number {
|
||||
if (!this.quiet) {
|
||||
header('Skill Tree');
|
||||
console.log(colors.muted(`${tree.totalSkills} skills in ${tree.totalCategories} categories`));
|
||||
console.log('');
|
||||
}
|
||||
|
||||
let targetNode: TreeNode = tree.rootNode;
|
||||
|
||||
if (this.treePath) {
|
||||
const segments = this.treePath.split('>').map((s) => s.trim());
|
||||
let current = tree.rootNode;
|
||||
|
||||
for (const segment of segments) {
|
||||
const child = current.children.find(
|
||||
(c) => c.name.toLowerCase() === segment.toLowerCase()
|
||||
);
|
||||
if (!child) {
|
||||
warn(`Category not found: ${segment}`);
|
||||
console.log(colors.muted(`Available categories: ${current.children.map((c) => c.name).join(', ')}`));
|
||||
return 1;
|
||||
}
|
||||
current = child;
|
||||
}
|
||||
targetNode = current;
|
||||
}
|
||||
|
||||
let maxDepth = this.depth ? parseInt(this.depth, 10) : 3;
|
||||
if (Number.isNaN(maxDepth) || maxDepth < 0) {
|
||||
warn('Invalid depth value. Using default depth of 3.');
|
||||
maxDepth = 3;
|
||||
}
|
||||
this.renderNode(targetNode, '', true, 0, maxDepth);
|
||||
|
||||
console.log('');
|
||||
console.log(colors.muted('Navigate: skillkit tree "Category > Subcategory"'));
|
||||
console.log(colors.muted('Generate: skillkit tree --generate'));
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
private renderNode(
|
||||
node: TreeNode,
|
||||
prefix: string,
|
||||
isLast: boolean,
|
||||
depth: number,
|
||||
maxDepth: number
|
||||
): void {
|
||||
if (depth > maxDepth) return;
|
||||
|
||||
const connector = depth === 0 ? '' : isLast ? '└── ' : '├── ';
|
||||
const icon = node.children.length > 0 ? '📁 ' : '📄 ';
|
||||
const skillInfo =
|
||||
node.skillCount > 0 ? colors.muted(` (${node.skillCount})`) : '';
|
||||
|
||||
const nameColor = depth === 0 ? colors.bold : depth === 1 ? colors.accent : colors.dim;
|
||||
|
||||
console.log(`${prefix}${connector}${icon}${nameColor(node.name)}${skillInfo}`);
|
||||
|
||||
if (depth === maxDepth && node.skills.length > 0 && node.skills.length <= 5) {
|
||||
const childPrefix = prefix + (isLast ? ' ' : '│ ');
|
||||
for (const skill of node.skills) {
|
||||
console.log(`${childPrefix} • ${colors.muted(skill)}`);
|
||||
}
|
||||
}
|
||||
|
||||
const newPrefix = prefix + (depth === 0 ? '' : isLast ? ' ' : '│ ');
|
||||
|
||||
if (depth < maxDepth) {
|
||||
node.children.forEach((child, index) => {
|
||||
const childIsLast = index === node.children.length - 1;
|
||||
this.renderNode(child, newPrefix, childIsLast, depth + 1, maxDepth);
|
||||
});
|
||||
} else if (node.children.length > 0) {
|
||||
console.log(`${newPrefix} ${colors.muted(`... ${node.children.length} more subcategories`)}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@skillkit/core",
|
||||
"version": "1.8.0",
|
||||
"version": "1.10.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",
|
||||
|
||||
@@ -0,0 +1,332 @@
|
||||
/**
|
||||
* Skill to Subagent Converter Tests
|
||||
*/
|
||||
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import {
|
||||
skillToSubagent,
|
||||
generateSubagentFromSkill,
|
||||
} from '../skill-converter.js';
|
||||
import type { Skill } from '../../types.js';
|
||||
|
||||
describe('Skill Converter', () => {
|
||||
const mockSkill: Skill = {
|
||||
name: 'code-simplifier',
|
||||
description: 'Simplifies and refines code for clarity and maintainability',
|
||||
path: '/path/to/skills/code-simplifier',
|
||||
location: 'project',
|
||||
enabled: true,
|
||||
};
|
||||
|
||||
const mockSkillContent = `---
|
||||
name: code-simplifier
|
||||
description: Simplifies and refines code for clarity and maintainability
|
||||
version: "1.0.0"
|
||||
author: skillkit
|
||||
tags: [refactoring, code-quality]
|
||||
allowed-tools: Edit, Read, Grep
|
||||
---
|
||||
|
||||
# Code Simplifier
|
||||
|
||||
You are an expert at simplifying code.
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Remove unnecessary complexity
|
||||
- Improve readability
|
||||
- Preserve functionality
|
||||
`;
|
||||
|
||||
describe('skillToSubagent', () => {
|
||||
it('should convert skill to canonical agent in reference mode', () => {
|
||||
const result = skillToSubagent(mockSkill, mockSkillContent);
|
||||
|
||||
expect(result.name).toBe('code-simplifier');
|
||||
expect(result.description).toBe('Simplifies and refines code for clarity and maintainability');
|
||||
expect(result.skills).toEqual(['code-simplifier']);
|
||||
expect(result.sourceFormat).toBe('claude-agent');
|
||||
expect(result.userInvocable).toBe(true);
|
||||
});
|
||||
|
||||
it('should not include skills array in inline mode', () => {
|
||||
const result = skillToSubagent(mockSkill, mockSkillContent, { inline: true });
|
||||
|
||||
expect(result.name).toBe('code-simplifier');
|
||||
expect(result.skills).toBeUndefined();
|
||||
expect(result.content).toContain('Code Simplifier');
|
||||
expect(result.content).toContain('Remove unnecessary complexity');
|
||||
});
|
||||
|
||||
it('should parse allowed-tools from skill frontmatter', () => {
|
||||
const result = skillToSubagent(mockSkill, mockSkillContent);
|
||||
|
||||
expect(result.allowedTools).toEqual(['Edit', 'Read', 'Grep']);
|
||||
});
|
||||
|
||||
it('should use option tools over frontmatter tools', () => {
|
||||
const result = skillToSubagent(mockSkill, mockSkillContent, {
|
||||
tools: ['Bash', 'Write'],
|
||||
});
|
||||
|
||||
expect(result.allowedTools).toEqual(['Bash', 'Write']);
|
||||
});
|
||||
|
||||
it('should set model from options', () => {
|
||||
const result = skillToSubagent(mockSkill, mockSkillContent, {
|
||||
model: 'opus',
|
||||
});
|
||||
|
||||
expect(result.model).toBe('opus');
|
||||
});
|
||||
|
||||
it('should not set model when inherit is specified', () => {
|
||||
const result = skillToSubagent(mockSkill, mockSkillContent, {
|
||||
model: 'inherit',
|
||||
});
|
||||
|
||||
expect(result.model).toBeUndefined();
|
||||
});
|
||||
|
||||
it('should set permission mode from options', () => {
|
||||
const result = skillToSubagent(mockSkill, mockSkillContent, {
|
||||
permissionMode: 'plan',
|
||||
});
|
||||
|
||||
expect(result.permissionMode).toBe('plan');
|
||||
});
|
||||
|
||||
it('should set disallowed tools from options', () => {
|
||||
const result = skillToSubagent(mockSkill, mockSkillContent, {
|
||||
disallowedTools: ['Bash', 'Write'],
|
||||
});
|
||||
|
||||
expect(result.disallowedTools).toEqual(['Bash', 'Write']);
|
||||
});
|
||||
|
||||
it('should preserve version and author from frontmatter', () => {
|
||||
const result = skillToSubagent(mockSkill, mockSkillContent);
|
||||
|
||||
expect(result.version).toBe('1.0.0');
|
||||
expect(result.author).toBe('skillkit');
|
||||
});
|
||||
|
||||
it('should preserve tags from frontmatter', () => {
|
||||
const result = skillToSubagent(mockSkill, mockSkillContent);
|
||||
|
||||
expect(result.tags).toEqual(['refactoring', 'code-quality']);
|
||||
});
|
||||
});
|
||||
|
||||
describe('generateSubagentFromSkill', () => {
|
||||
it('should generate valid markdown with frontmatter in reference mode', () => {
|
||||
const content = generateSubagentFromSkill(mockSkill, mockSkillContent);
|
||||
|
||||
expect(content).toContain('---');
|
||||
expect(content).toContain('name: code-simplifier');
|
||||
expect(content).toContain('description: Simplifies and refines code');
|
||||
expect(content).toContain('skills:');
|
||||
expect(content).toContain(' - code-simplifier');
|
||||
expect(content).toContain('user-invocable: true');
|
||||
});
|
||||
|
||||
it('should generate valid markdown in inline mode', () => {
|
||||
const content = generateSubagentFromSkill(mockSkill, mockSkillContent, { inline: true });
|
||||
|
||||
expect(content).toContain('---');
|
||||
expect(content).toContain('name: code-simplifier');
|
||||
expect(content).not.toContain('skills:');
|
||||
expect(content).toContain('# Code Simplifier');
|
||||
expect(content).toContain('Remove unnecessary complexity');
|
||||
});
|
||||
|
||||
it('should include tools in frontmatter', () => {
|
||||
const content = generateSubagentFromSkill(mockSkill, mockSkillContent);
|
||||
|
||||
expect(content).toContain('tools:');
|
||||
expect(content).toContain(' - Edit');
|
||||
expect(content).toContain(' - Read');
|
||||
expect(content).toContain(' - Grep');
|
||||
});
|
||||
|
||||
it('should include model in frontmatter when specified', () => {
|
||||
const content = generateSubagentFromSkill(mockSkill, mockSkillContent, {
|
||||
model: 'opus',
|
||||
});
|
||||
|
||||
expect(content).toContain('model: opus');
|
||||
});
|
||||
|
||||
it('should include permission mode in frontmatter when specified', () => {
|
||||
const content = generateSubagentFromSkill(mockSkill, mockSkillContent, {
|
||||
permissionMode: 'plan',
|
||||
});
|
||||
|
||||
expect(content).toContain('permissionMode: plan');
|
||||
});
|
||||
|
||||
it('should include disallowed tools in frontmatter when specified', () => {
|
||||
const content = generateSubagentFromSkill(mockSkill, mockSkillContent, {
|
||||
disallowedTools: ['Bash'],
|
||||
});
|
||||
|
||||
expect(content).toContain('disallowedTools:');
|
||||
expect(content).toContain(' - Bash');
|
||||
});
|
||||
|
||||
it('should include version and author in frontmatter', () => {
|
||||
const content = generateSubagentFromSkill(mockSkill, mockSkillContent);
|
||||
|
||||
expect(content).toContain('version: "1.0.0"');
|
||||
expect(content).toContain('author: skillkit');
|
||||
});
|
||||
|
||||
it('should include tags in frontmatter', () => {
|
||||
const content = generateSubagentFromSkill(mockSkill, mockSkillContent);
|
||||
|
||||
expect(content).toContain('tags: [refactoring, code-quality]');
|
||||
});
|
||||
|
||||
it('should generate reference content with skill description', () => {
|
||||
const content = generateSubagentFromSkill(mockSkill, mockSkillContent);
|
||||
|
||||
expect(content).toContain('# Code Simplifier');
|
||||
expect(content).toContain('uses the "code-simplifier" skill');
|
||||
expect(content).toContain('## Skill Description');
|
||||
expect(content).toContain('Simplifies and refines code');
|
||||
});
|
||||
|
||||
it('should embed full skill content in inline mode', () => {
|
||||
const content = generateSubagentFromSkill(mockSkill, mockSkillContent, { inline: true });
|
||||
|
||||
expect(content).toContain('You are a specialized assistant');
|
||||
expect(content).toContain('Remove unnecessary complexity');
|
||||
expect(content).toContain('Improve readability');
|
||||
expect(content).toContain('Preserve functionality');
|
||||
});
|
||||
});
|
||||
|
||||
describe('edge cases', () => {
|
||||
it('should handle skill without frontmatter', () => {
|
||||
const noFrontmatterContent = `# Simple Skill
|
||||
|
||||
Just some content without frontmatter.
|
||||
`;
|
||||
|
||||
const result = skillToSubagent(mockSkill, noFrontmatterContent);
|
||||
|
||||
expect(result.name).toBe('code-simplifier');
|
||||
expect(result.description).toBe('Simplifies and refines code for clarity and maintainability');
|
||||
expect(result.allowedTools).toBeUndefined();
|
||||
});
|
||||
|
||||
it('should handle skill with empty allowed-tools', () => {
|
||||
const contentWithEmptyTools = `---
|
||||
name: test-skill
|
||||
description: Test
|
||||
allowed-tools:
|
||||
---
|
||||
|
||||
Content here.
|
||||
`;
|
||||
|
||||
const skill: Skill = {
|
||||
name: 'test-skill',
|
||||
description: 'Test',
|
||||
path: '/path/to/test-skill',
|
||||
location: 'project',
|
||||
enabled: true,
|
||||
};
|
||||
|
||||
const result = skillToSubagent(skill, contentWithEmptyTools);
|
||||
|
||||
expect(result.allowedTools).toBeUndefined();
|
||||
});
|
||||
|
||||
it('should handle skill name with multiple hyphens', () => {
|
||||
const skill: Skill = {
|
||||
name: 'my-complex-skill-name',
|
||||
description: 'A complex skill',
|
||||
path: '/path/to/skill',
|
||||
location: 'project',
|
||||
enabled: true,
|
||||
};
|
||||
|
||||
const content = generateSubagentFromSkill(skill, `---
|
||||
name: my-complex-skill-name
|
||||
description: A complex skill
|
||||
---
|
||||
|
||||
Content.
|
||||
`);
|
||||
|
||||
expect(content).toContain('# My Complex Skill Name');
|
||||
});
|
||||
|
||||
it('should handle space-separated allowed-tools format', () => {
|
||||
const contentWithSpaceSeparated = `---
|
||||
name: test-skill
|
||||
description: Test
|
||||
allowed-tools: Bash(git:*) Read Write Edit
|
||||
---
|
||||
|
||||
Content here.
|
||||
`;
|
||||
|
||||
const skill: Skill = {
|
||||
name: 'test-skill',
|
||||
description: 'Test',
|
||||
path: '/path/to/test-skill',
|
||||
location: 'project',
|
||||
enabled: true,
|
||||
};
|
||||
|
||||
const result = skillToSubagent(skill, contentWithSpaceSeparated);
|
||||
|
||||
expect(result.allowedTools).toEqual(['Bash(git:*)', 'Read', 'Write', 'Edit']);
|
||||
});
|
||||
|
||||
it('should handle YAML array format for allowed-tools', () => {
|
||||
const contentWithArrayTools = `---
|
||||
name: test-skill
|
||||
description: Test
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash(npm:*)
|
||||
---
|
||||
|
||||
Content here.
|
||||
`;
|
||||
|
||||
const skill: Skill = {
|
||||
name: 'test-skill',
|
||||
description: 'Test',
|
||||
path: '/path/to/test-skill',
|
||||
location: 'project',
|
||||
enabled: true,
|
||||
};
|
||||
|
||||
const result = skillToSubagent(skill, contentWithArrayTools);
|
||||
|
||||
expect(result.allowedTools).toEqual(['Read', 'Write', 'Bash(npm:*)']);
|
||||
});
|
||||
|
||||
it('should handle CRLF line endings', () => {
|
||||
const crlfContent = `---\r\nname: test-skill\r\ndescription: Test\r\n---\r\n\r\n# Content\r\n\r\nWith CRLF endings.\r\n`;
|
||||
|
||||
const skill: Skill = {
|
||||
name: 'test-skill',
|
||||
description: 'Test',
|
||||
path: '/path/to/test-skill',
|
||||
location: 'project',
|
||||
enabled: true,
|
||||
};
|
||||
|
||||
const result = skillToSubagent(skill, crlfContent, { inline: true });
|
||||
|
||||
expect(result.content).toContain('# Content');
|
||||
expect(result.content).toContain('With CRLF endings.');
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -60,3 +60,11 @@ export {
|
||||
getAgentTargetDirectory,
|
||||
isAgentCompatible,
|
||||
} from './translator.js';
|
||||
|
||||
// Skill Converter
|
||||
export {
|
||||
skillToSubagent,
|
||||
generateSubagentFromSkill,
|
||||
loadAndConvertSkill,
|
||||
type SkillToSubagentOptions,
|
||||
} from './skill-converter.js';
|
||||
|
||||
@@ -0,0 +1,285 @@
|
||||
/**
|
||||
* Skill to Subagent Converter
|
||||
*
|
||||
* Converts SkillKit skills into Claude Code native subagent format (.md files).
|
||||
* Supports both reference mode (skills: [skill-name]) and inline mode (embedded content).
|
||||
*/
|
||||
|
||||
import type { Skill, SkillFrontmatter } from '../types.js';
|
||||
import type { CanonicalAgent, AgentPermissionMode } from './types.js';
|
||||
import { extractFrontmatter, readSkillContent } from '../skills.js';
|
||||
|
||||
/**
|
||||
* Options for skill-to-subagent conversion
|
||||
*/
|
||||
export interface SkillToSubagentOptions {
|
||||
/** Embed full skill content in system prompt (default: false - use skills reference) */
|
||||
inline?: boolean;
|
||||
/** Model to use (sonnet, opus, haiku, inherit) */
|
||||
model?: 'sonnet' | 'opus' | 'haiku' | 'inherit';
|
||||
/** Permission mode for the agent */
|
||||
permissionMode?: AgentPermissionMode;
|
||||
/** Tools the agent is allowed to use */
|
||||
tools?: string[];
|
||||
/** Tools the agent cannot use */
|
||||
disallowedTools?: string[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Convert a skill to a CanonicalAgent representation
|
||||
*/
|
||||
export function skillToSubagent(
|
||||
skill: Skill,
|
||||
skillContent: string,
|
||||
options?: SkillToSubagentOptions
|
||||
): CanonicalAgent {
|
||||
const frontmatter = extractFrontmatter(skillContent) as Partial<SkillFrontmatter> | null;
|
||||
const inline = options?.inline ?? false;
|
||||
|
||||
const allowedTools = parseAllowedTools(frontmatter, options?.tools);
|
||||
const content = inline
|
||||
? generateInlineContent(skill, skillContent)
|
||||
: generateReferenceContent(skill, frontmatter);
|
||||
|
||||
return {
|
||||
name: skill.name,
|
||||
description: skill.description,
|
||||
model: options?.model === 'inherit' ? undefined : options?.model,
|
||||
permissionMode: options?.permissionMode,
|
||||
disallowedTools: options?.disallowedTools,
|
||||
allowedTools,
|
||||
skills: inline ? undefined : [skill.name],
|
||||
content,
|
||||
sourceFormat: 'claude-agent',
|
||||
sourceAgent: 'claude-code',
|
||||
version: frontmatter?.version,
|
||||
author: frontmatter?.author,
|
||||
tags: frontmatter?.tags,
|
||||
userInvocable: true,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate the markdown content for a Claude Code subagent from a skill
|
||||
*/
|
||||
export function generateSubagentFromSkill(
|
||||
skill: Skill,
|
||||
skillContent: string,
|
||||
options?: SkillToSubagentOptions
|
||||
): string {
|
||||
const canonical = skillToSubagent(skill, skillContent, options);
|
||||
return generateSubagentMarkdown(canonical, options?.inline ?? false);
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse allowed-tools from skill frontmatter
|
||||
* Handles both string (comma or space-separated) and array formats
|
||||
*/
|
||||
function parseAllowedTools(
|
||||
frontmatter: Partial<SkillFrontmatter> | null,
|
||||
optionTools?: string[]
|
||||
): string[] | undefined {
|
||||
if (optionTools && optionTools.length > 0) {
|
||||
return optionTools;
|
||||
}
|
||||
|
||||
const allowedTools = frontmatter?.['allowed-tools'];
|
||||
if (!allowedTools) {
|
||||
return undefined;
|
||||
}
|
||||
|
||||
if (Array.isArray(allowedTools)) {
|
||||
const result = allowedTools
|
||||
.map(t => (typeof t === 'string' ? t.trim() : ''))
|
||||
.filter(Boolean);
|
||||
return result.length > 0 ? result : undefined;
|
||||
}
|
||||
|
||||
if (typeof allowedTools === 'string') {
|
||||
const result = allowedTools
|
||||
.split(/[,\s]+/)
|
||||
.map(t => t.trim())
|
||||
.filter(Boolean);
|
||||
return result.length > 0 ? result : undefined;
|
||||
}
|
||||
|
||||
return undefined;
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate inline content (full skill embedded)
|
||||
*/
|
||||
function generateInlineContent(skill: Skill, skillContent: string): string {
|
||||
const bodyContent = extractBodyContent(skillContent);
|
||||
|
||||
const lines: string[] = [];
|
||||
lines.push(`# ${formatAgentName(skill.name)}`);
|
||||
lines.push('');
|
||||
lines.push('You are a specialized assistant powered by the following skill.');
|
||||
lines.push('');
|
||||
lines.push('---');
|
||||
lines.push('');
|
||||
lines.push(bodyContent.trim());
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate reference content (skill referenced by name)
|
||||
*/
|
||||
function generateReferenceContent(
|
||||
skill: Skill,
|
||||
frontmatter: Partial<SkillFrontmatter> | null
|
||||
): string {
|
||||
const lines: string[] = [];
|
||||
lines.push(`# ${formatAgentName(skill.name)}`);
|
||||
lines.push('');
|
||||
lines.push(`You are a specialized assistant that uses the "${skill.name}" skill.`);
|
||||
lines.push('');
|
||||
lines.push('## Skill Description');
|
||||
lines.push('');
|
||||
lines.push(skill.description);
|
||||
lines.push('');
|
||||
lines.push('## Usage');
|
||||
lines.push('');
|
||||
lines.push(`This agent automatically loads the "${skill.name}" skill.`);
|
||||
lines.push('Follow the skill instructions to complete tasks effectively.');
|
||||
|
||||
if (frontmatter?.tags && frontmatter.tags.length > 0) {
|
||||
lines.push('');
|
||||
lines.push('## Related Topics');
|
||||
lines.push('');
|
||||
lines.push(frontmatter.tags.map(t => `- ${t}`).join('\n'));
|
||||
}
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate full subagent markdown file content
|
||||
*/
|
||||
function generateSubagentMarkdown(
|
||||
canonical: CanonicalAgent,
|
||||
isInline: boolean
|
||||
): string {
|
||||
const lines: string[] = ['---'];
|
||||
|
||||
lines.push(`name: ${escapeYamlString(canonical.name)}`);
|
||||
lines.push(`description: ${escapeYamlString(canonical.description)}`);
|
||||
|
||||
if (canonical.model) {
|
||||
lines.push(`model: ${canonical.model}`);
|
||||
}
|
||||
if (canonical.permissionMode) {
|
||||
lines.push(`permissionMode: ${canonical.permissionMode}`);
|
||||
}
|
||||
|
||||
appendYamlList(lines, 'tools', canonical.allowedTools);
|
||||
appendYamlList(lines, 'disallowedTools', canonical.disallowedTools);
|
||||
|
||||
if (!isInline) {
|
||||
appendYamlList(lines, 'skills', canonical.skills);
|
||||
}
|
||||
|
||||
if (canonical.version) {
|
||||
lines.push(`version: "${canonical.version}"`);
|
||||
}
|
||||
if (canonical.author) {
|
||||
lines.push(`author: ${escapeYamlString(canonical.author)}`);
|
||||
}
|
||||
if (canonical.tags && canonical.tags.length > 0) {
|
||||
lines.push(`tags: [${canonical.tags.map(t => escapeYamlString(t)).join(', ')}]`);
|
||||
}
|
||||
if (canonical.userInvocable !== undefined) {
|
||||
lines.push(`user-invocable: ${canonical.userInvocable}`);
|
||||
}
|
||||
|
||||
lines.push('---', '', canonical.content);
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
function appendYamlList(lines: string[], key: string, items?: string[]): void {
|
||||
if (!items || items.length === 0) return;
|
||||
lines.push(`${key}:`);
|
||||
for (const item of items) {
|
||||
lines.push(` - ${escapeYamlString(item)}`);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Extract body content from skill markdown (without frontmatter)
|
||||
* Handles both Unix (LF) and Windows (CRLF) line endings
|
||||
*/
|
||||
function extractBodyContent(content: string): string {
|
||||
const normalized = content.replace(/\r\n/g, '\n');
|
||||
const match = normalized.match(/^---\s*\n[\s\S]*?\n---\s*\n([\s\S]*)$/);
|
||||
if (match) {
|
||||
return match[1];
|
||||
}
|
||||
return content;
|
||||
}
|
||||
|
||||
/**
|
||||
* Format agent name for display (kebab-case to Title Case)
|
||||
*/
|
||||
function formatAgentName(name: string): string {
|
||||
return name
|
||||
.split('-')
|
||||
.map(word => word.charAt(0).toUpperCase() + word.slice(1))
|
||||
.join(' ');
|
||||
}
|
||||
|
||||
/**
|
||||
* Escape special characters in YAML strings
|
||||
* Only escapes when necessary for valid YAML parsing
|
||||
*/
|
||||
function escapeYamlString(str: string): string {
|
||||
if (
|
||||
str.includes('\n') ||
|
||||
str.includes(':') ||
|
||||
str.includes('#') ||
|
||||
str.startsWith('-') ||
|
||||
str.startsWith('*') ||
|
||||
str.startsWith('&') ||
|
||||
str.startsWith('!') ||
|
||||
str.startsWith('{') ||
|
||||
str.startsWith('[') ||
|
||||
str.startsWith('>') ||
|
||||
str.startsWith('|') ||
|
||||
str.startsWith('@') ||
|
||||
str.startsWith('`') ||
|
||||
/^['"]/.test(str)
|
||||
) {
|
||||
return `"${str.replace(/"/g, '\\"').replace(/\n/g, '\\n')}"`;
|
||||
}
|
||||
return str;
|
||||
}
|
||||
|
||||
/**
|
||||
* Load a skill and generate subagent content
|
||||
* Convenience function that reads skill content and generates subagent markdown
|
||||
*/
|
||||
export function loadAndConvertSkill(
|
||||
skill: Skill,
|
||||
options?: SkillToSubagentOptions
|
||||
): { success: boolean; content?: string; error?: string } {
|
||||
const skillContent = readSkillContent(skill.path);
|
||||
|
||||
if (!skillContent) {
|
||||
return {
|
||||
success: false,
|
||||
error: `Could not read skill content from: ${skill.path}`,
|
||||
};
|
||||
}
|
||||
|
||||
try {
|
||||
const content = generateSubagentFromSkill(skill, skillContent, options);
|
||||
return { success: true, content };
|
||||
} catch (err) {
|
||||
return {
|
||||
success: false,
|
||||
error: err instanceof Error ? err.message : 'Unknown error',
|
||||
};
|
||||
}
|
||||
}
|
||||
@@ -64,7 +64,12 @@ export const AgentFrontmatter = z.object({
|
||||
/** Allowed tools for this agent */
|
||||
allowedTools: z.union([
|
||||
z.array(z.string()),
|
||||
z.string(), // YAML-style list in frontmatter
|
||||
z.string(),
|
||||
]).optional(),
|
||||
/** Tools (Claude Code native format alias for allowedTools) */
|
||||
tools: z.union([
|
||||
z.array(z.string()),
|
||||
z.string(),
|
||||
]).optional(),
|
||||
/** Agent-scoped hooks */
|
||||
hooks: z.array(AgentHook).optional(),
|
||||
|
||||
@@ -0,0 +1,22 @@
|
||||
export * from './types.js';
|
||||
export * from './utils.js';
|
||||
|
||||
export {
|
||||
STANDARD_PLACEHOLDERS,
|
||||
ConnectorCategorySchema,
|
||||
ConnectorPlaceholderSchema,
|
||||
ConnectorMappingSchema,
|
||||
ConnectorConfigSchema,
|
||||
} from './types.js';
|
||||
|
||||
export {
|
||||
detectPlaceholders,
|
||||
analyzePlaceholders,
|
||||
replacePlaceholders,
|
||||
applyConnectorConfig,
|
||||
getPlaceholderInfo,
|
||||
generateConnectorsMarkdown,
|
||||
createConnectorConfig,
|
||||
validateConnectorConfig,
|
||||
suggestMappingsFromMcp,
|
||||
} from './utils.js';
|
||||
@@ -0,0 +1,162 @@
|
||||
import { z } from 'zod';
|
||||
|
||||
export const ConnectorCategorySchema = z.enum([
|
||||
'crm',
|
||||
'chat',
|
||||
'email',
|
||||
'calendar',
|
||||
'docs',
|
||||
'data',
|
||||
'search',
|
||||
'enrichment',
|
||||
'analytics',
|
||||
'storage',
|
||||
'notifications',
|
||||
'ai',
|
||||
'custom',
|
||||
]);
|
||||
|
||||
export type ConnectorCategory = z.infer<typeof ConnectorCategorySchema>;
|
||||
|
||||
export const ConnectorPlaceholderSchema = z.object({
|
||||
placeholder: z.string(),
|
||||
category: ConnectorCategorySchema,
|
||||
description: z.string(),
|
||||
examples: z.array(z.string()).default([]),
|
||||
required: z.boolean().default(false),
|
||||
});
|
||||
|
||||
export type ConnectorPlaceholder = z.infer<typeof ConnectorPlaceholderSchema>;
|
||||
|
||||
export const ConnectorMappingSchema = z.object({
|
||||
placeholder: z.string(),
|
||||
tool: z.string(),
|
||||
mcpServer: z.string().optional(),
|
||||
config: z.record(z.unknown()).optional(),
|
||||
});
|
||||
|
||||
export type ConnectorMapping = z.infer<typeof ConnectorMappingSchema>;
|
||||
|
||||
export const ConnectorConfigSchema = z.object({
|
||||
version: z.number().default(1),
|
||||
mappings: z.array(ConnectorMappingSchema),
|
||||
description: z.string().optional(),
|
||||
});
|
||||
|
||||
export type ConnectorConfig = z.infer<typeof ConnectorConfigSchema>;
|
||||
|
||||
export const STANDARD_PLACEHOLDERS: Record<ConnectorCategory, ConnectorPlaceholder> = {
|
||||
crm: {
|
||||
placeholder: '~~CRM',
|
||||
category: 'crm',
|
||||
description: 'Customer Relationship Management system',
|
||||
examples: ['Salesforce', 'HubSpot', 'Pipedrive', 'Zoho CRM'],
|
||||
required: false,
|
||||
},
|
||||
chat: {
|
||||
placeholder: '~~chat',
|
||||
category: 'chat',
|
||||
description: 'Team communication and messaging platform',
|
||||
examples: ['Slack', 'Microsoft Teams', 'Discord'],
|
||||
required: false,
|
||||
},
|
||||
email: {
|
||||
placeholder: '~~email',
|
||||
category: 'email',
|
||||
description: 'Email service for sending and receiving messages',
|
||||
examples: ['Gmail', 'Outlook', 'SendGrid'],
|
||||
required: false,
|
||||
},
|
||||
calendar: {
|
||||
placeholder: '~~calendar',
|
||||
category: 'calendar',
|
||||
description: 'Calendar and scheduling system',
|
||||
examples: ['Google Calendar', 'Outlook Calendar', 'Calendly'],
|
||||
required: false,
|
||||
},
|
||||
docs: {
|
||||
placeholder: '~~docs',
|
||||
category: 'docs',
|
||||
description: 'Document management and collaboration',
|
||||
examples: ['Google Docs', 'Notion', 'Confluence', 'Coda'],
|
||||
required: false,
|
||||
},
|
||||
data: {
|
||||
placeholder: '~~data',
|
||||
category: 'data',
|
||||
description: 'Data warehouse or database',
|
||||
examples: ['BigQuery', 'Snowflake', 'PostgreSQL', 'Databricks'],
|
||||
required: false,
|
||||
},
|
||||
search: {
|
||||
placeholder: '~~search',
|
||||
category: 'search',
|
||||
description: 'Enterprise search across tools',
|
||||
examples: ['Glean', 'Elastic', 'Algolia'],
|
||||
required: false,
|
||||
},
|
||||
enrichment: {
|
||||
placeholder: '~~enrichment',
|
||||
category: 'enrichment',
|
||||
description: 'Data enrichment service',
|
||||
examples: ['Clearbit', 'ZoomInfo', 'Apollo'],
|
||||
required: false,
|
||||
},
|
||||
analytics: {
|
||||
placeholder: '~~analytics',
|
||||
category: 'analytics',
|
||||
description: 'Analytics and reporting platform',
|
||||
examples: ['Mixpanel', 'Amplitude', 'Google Analytics'],
|
||||
required: false,
|
||||
},
|
||||
storage: {
|
||||
placeholder: '~~storage',
|
||||
category: 'storage',
|
||||
description: 'File storage service',
|
||||
examples: ['Google Drive', 'Dropbox', 'S3', 'Box'],
|
||||
required: false,
|
||||
},
|
||||
notifications: {
|
||||
placeholder: '~~notifications',
|
||||
category: 'notifications',
|
||||
description: 'Notification and alerting service',
|
||||
examples: ['PagerDuty', 'Opsgenie', 'SMS'],
|
||||
required: false,
|
||||
},
|
||||
ai: {
|
||||
placeholder: '~~ai',
|
||||
category: 'ai',
|
||||
description: 'AI/ML model or service',
|
||||
examples: ['OpenAI', 'Anthropic', 'Hugging Face'],
|
||||
required: false,
|
||||
},
|
||||
custom: {
|
||||
placeholder: '~~custom',
|
||||
category: 'custom',
|
||||
description: 'Custom integration',
|
||||
examples: [],
|
||||
required: false,
|
||||
},
|
||||
};
|
||||
|
||||
export interface PlaceholderMatch {
|
||||
placeholder: string;
|
||||
category: ConnectorCategory | null;
|
||||
line: number;
|
||||
column: number;
|
||||
context: string;
|
||||
}
|
||||
|
||||
export interface PlaceholderReplacement {
|
||||
original: string;
|
||||
replacement: string;
|
||||
category: ConnectorCategory | null;
|
||||
}
|
||||
|
||||
export interface ConnectorAnalysis {
|
||||
placeholders: PlaceholderMatch[];
|
||||
categories: ConnectorCategory[];
|
||||
requiredCount: number;
|
||||
optionalCount: number;
|
||||
hasUnknownPlaceholders: boolean;
|
||||
}
|
||||
@@ -0,0 +1,268 @@
|
||||
import {
|
||||
type ConnectorCategory,
|
||||
type ConnectorPlaceholder,
|
||||
type ConnectorMapping,
|
||||
type ConnectorConfig,
|
||||
type PlaceholderMatch,
|
||||
type PlaceholderReplacement,
|
||||
type ConnectorAnalysis,
|
||||
STANDARD_PLACEHOLDERS,
|
||||
ConnectorCategorySchema,
|
||||
} from './types.js';
|
||||
|
||||
const PLACEHOLDER_REGEX = /~~(\w+)/g;
|
||||
|
||||
export function detectPlaceholders(content: string): PlaceholderMatch[] {
|
||||
const matches: PlaceholderMatch[] = [];
|
||||
const lines = content.split('\n');
|
||||
|
||||
for (let lineNum = 0; lineNum < lines.length; lineNum++) {
|
||||
const line = lines[lineNum];
|
||||
let match: RegExpExecArray | null;
|
||||
|
||||
const regex = new RegExp(PLACEHOLDER_REGEX.source, 'g');
|
||||
while ((match = regex.exec(line)) !== null) {
|
||||
const placeholder = match[0];
|
||||
const categoryName = match[1].toLowerCase();
|
||||
|
||||
let category: ConnectorCategory | null = null;
|
||||
try {
|
||||
category = ConnectorCategorySchema.parse(categoryName);
|
||||
} catch {
|
||||
category = null;
|
||||
}
|
||||
|
||||
const contextStart = Math.max(0, match.index - 20);
|
||||
const contextEnd = Math.min(line.length, match.index + placeholder.length + 20);
|
||||
const context = line.slice(contextStart, contextEnd);
|
||||
|
||||
matches.push({
|
||||
placeholder,
|
||||
category,
|
||||
line: lineNum + 1,
|
||||
column: match.index + 1,
|
||||
context: context.trim(),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
return matches;
|
||||
}
|
||||
|
||||
export function analyzePlaceholders(content: string): ConnectorAnalysis {
|
||||
const matches = detectPlaceholders(content);
|
||||
const categories = new Set<ConnectorCategory>();
|
||||
let requiredCount = 0;
|
||||
let optionalCount = 0;
|
||||
let hasUnknownPlaceholders = false;
|
||||
|
||||
for (const match of matches) {
|
||||
if (match.category) {
|
||||
categories.add(match.category);
|
||||
const standardPlaceholder = STANDARD_PLACEHOLDERS[match.category];
|
||||
if (standardPlaceholder?.required) {
|
||||
requiredCount++;
|
||||
} else {
|
||||
optionalCount++;
|
||||
}
|
||||
} else {
|
||||
hasUnknownPlaceholders = true;
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
placeholders: matches,
|
||||
categories: Array.from(categories),
|
||||
requiredCount,
|
||||
optionalCount,
|
||||
hasUnknownPlaceholders,
|
||||
};
|
||||
}
|
||||
|
||||
export function replacePlaceholders(
|
||||
content: string,
|
||||
mappings: ConnectorMapping[]
|
||||
): { result: string; replacements: PlaceholderReplacement[] } {
|
||||
const replacements: PlaceholderReplacement[] = [];
|
||||
let result = content;
|
||||
|
||||
for (const mapping of mappings) {
|
||||
const regex = new RegExp(escapeRegExp(mapping.placeholder), 'g');
|
||||
const originalMatches = content.match(regex);
|
||||
|
||||
if (originalMatches) {
|
||||
result = result.replace(regex, mapping.tool);
|
||||
|
||||
const categoryName = mapping.placeholder.replace('~~', '').toLowerCase();
|
||||
let category: ConnectorCategory | null = null;
|
||||
try {
|
||||
category = ConnectorCategorySchema.parse(categoryName);
|
||||
} catch {
|
||||
category = null;
|
||||
}
|
||||
|
||||
replacements.push({
|
||||
original: mapping.placeholder,
|
||||
replacement: mapping.tool,
|
||||
category,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
return { result, replacements };
|
||||
}
|
||||
|
||||
export function applyConnectorConfig(
|
||||
content: string,
|
||||
config: ConnectorConfig
|
||||
): { result: string; replacements: PlaceholderReplacement[] } {
|
||||
return replacePlaceholders(content, config.mappings);
|
||||
}
|
||||
|
||||
export function getPlaceholderInfo(placeholder: string): ConnectorPlaceholder | null {
|
||||
const categoryName = placeholder.replace('~~', '').toLowerCase();
|
||||
|
||||
try {
|
||||
const category = ConnectorCategorySchema.parse(categoryName);
|
||||
return STANDARD_PLACEHOLDERS[category];
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
export function generateConnectorsMarkdown(analysis: ConnectorAnalysis): string {
|
||||
const lines: string[] = [];
|
||||
|
||||
lines.push('# Connectors');
|
||||
lines.push('');
|
||||
lines.push('This skill uses the following connector placeholders. Replace them with your specific tools.');
|
||||
lines.push('');
|
||||
lines.push('| Placeholder | Category | Description | Examples |');
|
||||
lines.push('|-------------|----------|-------------|----------|');
|
||||
|
||||
for (const match of analysis.placeholders) {
|
||||
if (match.category) {
|
||||
const info = STANDARD_PLACEHOLDERS[match.category];
|
||||
lines.push(
|
||||
`| \`${match.placeholder}\` | ${match.category} | ${info.description} | ${info.examples.slice(0, 3).join(', ')} |`
|
||||
);
|
||||
} else {
|
||||
lines.push(
|
||||
`| \`${match.placeholder}\` | custom | Custom integration | - |`
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
lines.push('');
|
||||
lines.push('## How to Customize');
|
||||
lines.push('');
|
||||
lines.push('1. Find all placeholders: `grep -n "~~" SKILL.md`');
|
||||
lines.push('2. Replace each `~~category` with your specific tool name');
|
||||
lines.push('3. Configure MCP server in `.mcp.json` if needed');
|
||||
lines.push('');
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
export function createConnectorConfig(
|
||||
mappings: Array<{ placeholder: string; tool: string; mcpServer?: string }>
|
||||
): ConnectorConfig {
|
||||
return {
|
||||
version: 1,
|
||||
mappings: mappings.map((m) => ({
|
||||
placeholder: m.placeholder,
|
||||
tool: m.tool,
|
||||
mcpServer: m.mcpServer,
|
||||
})),
|
||||
};
|
||||
}
|
||||
|
||||
export function validateConnectorConfig(
|
||||
config: ConnectorConfig,
|
||||
content: string
|
||||
): { valid: boolean; errors: string[]; warnings: string[] } {
|
||||
const errors: string[] = [];
|
||||
const warnings: string[] = [];
|
||||
|
||||
const analysis = analyzePlaceholders(content);
|
||||
const placeholdersInContent = new Set(analysis.placeholders.map((p) => p.placeholder));
|
||||
const mappedPlaceholders = new Set(config.mappings.map((m) => m.placeholder));
|
||||
|
||||
for (const placeholder of placeholdersInContent) {
|
||||
if (!mappedPlaceholders.has(placeholder)) {
|
||||
const info = getPlaceholderInfo(placeholder);
|
||||
if (info?.required) {
|
||||
errors.push(`Required placeholder ${placeholder} is not mapped`);
|
||||
} else {
|
||||
warnings.push(`Optional placeholder ${placeholder} is not mapped`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
for (const mapping of config.mappings) {
|
||||
if (!placeholdersInContent.has(mapping.placeholder)) {
|
||||
warnings.push(`Mapping for ${mapping.placeholder} exists but placeholder not found in content`);
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
valid: errors.length === 0,
|
||||
errors,
|
||||
warnings,
|
||||
};
|
||||
}
|
||||
|
||||
export function suggestMappingsFromMcp(
|
||||
mcpServers: string[]
|
||||
): ConnectorMapping[] {
|
||||
const suggestions: ConnectorMapping[] = [];
|
||||
const serverLower = mcpServers.map((s) => s.toLowerCase());
|
||||
|
||||
const serverToCategory: Record<string, { category: ConnectorCategory; tool: string }[]> = {
|
||||
slack: [{ category: 'chat', tool: 'Slack' }],
|
||||
teams: [{ category: 'chat', tool: 'Microsoft Teams' }],
|
||||
discord: [{ category: 'chat', tool: 'Discord' }],
|
||||
gmail: [{ category: 'email', tool: 'Gmail' }],
|
||||
outlook: [{ category: 'email', tool: 'Outlook' }],
|
||||
sendgrid: [{ category: 'email', tool: 'SendGrid' }],
|
||||
salesforce: [{ category: 'crm', tool: 'Salesforce' }],
|
||||
hubspot: [{ category: 'crm', tool: 'HubSpot' }],
|
||||
pipedrive: [{ category: 'crm', tool: 'Pipedrive' }],
|
||||
notion: [{ category: 'docs', tool: 'Notion' }],
|
||||
confluence: [{ category: 'docs', tool: 'Confluence' }],
|
||||
google: [
|
||||
{ category: 'docs', tool: 'Google Docs' },
|
||||
{ category: 'calendar', tool: 'Google Calendar' },
|
||||
{ category: 'storage', tool: 'Google Drive' },
|
||||
],
|
||||
bigquery: [{ category: 'data', tool: 'BigQuery' }],
|
||||
snowflake: [{ category: 'data', tool: 'Snowflake' }],
|
||||
postgres: [{ category: 'data', tool: 'PostgreSQL' }],
|
||||
supabase: [{ category: 'data', tool: 'Supabase' }],
|
||||
clearbit: [{ category: 'enrichment', tool: 'Clearbit' }],
|
||||
zoominfo: [{ category: 'enrichment', tool: 'ZoomInfo' }],
|
||||
apollo: [{ category: 'enrichment', tool: 'Apollo' }],
|
||||
openai: [{ category: 'ai', tool: 'OpenAI' }],
|
||||
anthropic: [{ category: 'ai', tool: 'Anthropic Claude' }],
|
||||
};
|
||||
|
||||
for (const server of serverLower) {
|
||||
for (const [keyword, mappings] of Object.entries(serverToCategory)) {
|
||||
if (server.includes(keyword)) {
|
||||
for (const mapping of mappings) {
|
||||
suggestions.push({
|
||||
placeholder: STANDARD_PLACEHOLDERS[mapping.category].placeholder,
|
||||
tool: mapping.tool,
|
||||
mcpServer: server,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return suggestions;
|
||||
}
|
||||
|
||||
function escapeRegExp(string: string): string {
|
||||
return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
||||
}
|
||||
@@ -0,0 +1,23 @@
|
||||
export * from './types.js';
|
||||
export * from './manager.js';
|
||||
export * from './mode.js';
|
||||
|
||||
export {
|
||||
ExecutionManager,
|
||||
createExecutionManager,
|
||||
} from './manager.js';
|
||||
|
||||
export {
|
||||
ExecutionStepStatusSchema,
|
||||
ExecutionStepSchema,
|
||||
ExecutionFlowSchema,
|
||||
} from './types.js';
|
||||
|
||||
export {
|
||||
detectExecutionMode,
|
||||
getModeDescription,
|
||||
requireEnhancedMode,
|
||||
requireCapability,
|
||||
getStandaloneAlternative,
|
||||
createModeAwareExecutor,
|
||||
} from './mode.js';
|
||||
@@ -0,0 +1,314 @@
|
||||
import { randomUUID } from 'node:crypto';
|
||||
import {
|
||||
type ExecutionFlow,
|
||||
type ExecutionStep,
|
||||
type ExecutionFlowConfig,
|
||||
type StepDefinition,
|
||||
type ExecutionContext,
|
||||
type FlowSummary,
|
||||
type FlowMetrics,
|
||||
ExecutionFlowSchema,
|
||||
} from './types.js';
|
||||
|
||||
const DEFAULT_MAX_RETRIES = 3;
|
||||
const DEFAULT_RETRY_DELAY = 1000;
|
||||
const DEFAULT_TIMEOUT = 30000;
|
||||
|
||||
export class ExecutionManager {
|
||||
private flows: Map<string, ExecutionFlow> = new Map();
|
||||
private stepDefinitions: Map<string, Map<string, StepDefinition>> = new Map();
|
||||
private config: ExecutionFlowConfig;
|
||||
private metrics: FlowMetrics;
|
||||
|
||||
constructor(config: ExecutionFlowConfig = {}) {
|
||||
this.config = config;
|
||||
this.metrics = {
|
||||
totalFlows: 0,
|
||||
completedFlows: 0,
|
||||
failedFlows: 0,
|
||||
averageDuration: 0,
|
||||
stepMetrics: new Map(),
|
||||
};
|
||||
}
|
||||
|
||||
createFlow(
|
||||
skillName: string,
|
||||
steps: Array<{ name: string; description?: string }>,
|
||||
options: {
|
||||
mode?: 'standalone' | 'enhanced';
|
||||
mcpServers?: string[];
|
||||
context?: Record<string, unknown>;
|
||||
} = {}
|
||||
): ExecutionFlow {
|
||||
const flowId = randomUUID();
|
||||
const executionSteps: ExecutionStep[] = steps.map((step, index) => ({
|
||||
id: `${flowId}-step-${index}`,
|
||||
name: step.name,
|
||||
description: step.description,
|
||||
status: 'pending',
|
||||
retryCount: 0,
|
||||
}));
|
||||
|
||||
const flow: ExecutionFlow = ExecutionFlowSchema.parse({
|
||||
id: flowId,
|
||||
skillName,
|
||||
version: 1,
|
||||
steps: executionSteps,
|
||||
currentStepIndex: -1,
|
||||
status: 'pending',
|
||||
context: options.context,
|
||||
mode: options.mode || 'standalone',
|
||||
mcpServers: options.mcpServers,
|
||||
});
|
||||
|
||||
this.flows.set(flowId, flow);
|
||||
this.metrics.totalFlows++;
|
||||
|
||||
return flow;
|
||||
}
|
||||
|
||||
registerStepDefinitions(skillName: string, definitions: StepDefinition[]): void {
|
||||
const skillSteps = new Map<string, StepDefinition>();
|
||||
for (const def of definitions) {
|
||||
skillSteps.set(def.name, def);
|
||||
}
|
||||
this.stepDefinitions.set(skillName, skillSteps);
|
||||
}
|
||||
|
||||
async executeFlow(flowId: string): Promise<ExecutionFlow> {
|
||||
const flow = this.flows.get(flowId);
|
||||
if (!flow) {
|
||||
throw new Error(`Flow ${flowId} not found`);
|
||||
}
|
||||
|
||||
flow.status = 'running';
|
||||
flow.startedAt = new Date().toISOString();
|
||||
|
||||
const skillSteps = this.stepDefinitions.get(flow.skillName);
|
||||
|
||||
try {
|
||||
let previousOutput: Record<string, unknown> = {};
|
||||
|
||||
for (let i = 0; i < flow.steps.length; i++) {
|
||||
const step = flow.steps[i];
|
||||
flow.currentStepIndex = i;
|
||||
|
||||
const context: ExecutionContext = {
|
||||
flow,
|
||||
stepIndex: i,
|
||||
previousOutput,
|
||||
mcpTools: flow.mcpServers,
|
||||
isEnhanced: flow.mode === 'enhanced',
|
||||
};
|
||||
|
||||
const stepDef = skillSteps?.get(step.name);
|
||||
|
||||
if (stepDef?.condition && !stepDef.condition(context)) {
|
||||
step.status = 'skipped';
|
||||
continue;
|
||||
}
|
||||
|
||||
const result = await this.executeStep(step, stepDef, context);
|
||||
|
||||
if (result.status === 'completed' && result.output) {
|
||||
previousOutput = { ...previousOutput, ...result.output };
|
||||
}
|
||||
|
||||
if (result.status === 'failed') {
|
||||
flow.status = 'failed';
|
||||
flow.completedAt = new Date().toISOString();
|
||||
flow.totalDuration = this.calculateDuration(flow.startedAt, flow.completedAt);
|
||||
this.metrics.failedFlows++;
|
||||
this.config.onFlowComplete?.(flow);
|
||||
return flow;
|
||||
}
|
||||
}
|
||||
|
||||
flow.status = 'completed';
|
||||
flow.completedAt = new Date().toISOString();
|
||||
flow.totalDuration = this.calculateDuration(flow.startedAt, flow.completedAt);
|
||||
this.metrics.completedFlows++;
|
||||
this.updateAverageDuration(flow.totalDuration);
|
||||
this.config.onFlowComplete?.(flow);
|
||||
|
||||
return flow;
|
||||
} catch (error) {
|
||||
flow.status = 'failed';
|
||||
flow.completedAt = new Date().toISOString();
|
||||
flow.totalDuration = this.calculateDuration(flow.startedAt, flow.completedAt);
|
||||
this.metrics.failedFlows++;
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
private async executeStep(
|
||||
step: ExecutionStep,
|
||||
stepDef: StepDefinition | undefined,
|
||||
context: ExecutionContext
|
||||
): Promise<ExecutionStep> {
|
||||
const maxRetries = this.config.maxRetries ?? DEFAULT_MAX_RETRIES;
|
||||
const retryDelay = this.config.retryDelay ?? DEFAULT_RETRY_DELAY;
|
||||
const timeout = stepDef?.timeout ?? this.config.timeout ?? DEFAULT_TIMEOUT;
|
||||
|
||||
step.status = 'running';
|
||||
step.startedAt = new Date().toISOString();
|
||||
this.config.onStepStart?.(step, context.flow);
|
||||
|
||||
let lastError: Error | null = null;
|
||||
|
||||
while (step.retryCount <= maxRetries) {
|
||||
let timeoutId: ReturnType<typeof setTimeout> | undefined;
|
||||
try {
|
||||
if (stepDef) {
|
||||
const timeoutPromise = new Promise<never>((_, reject) => {
|
||||
timeoutId = setTimeout(
|
||||
() => reject(new Error(`Step ${step.name} timed out`)),
|
||||
timeout
|
||||
);
|
||||
});
|
||||
|
||||
const executePromise = stepDef.execute(step.input || {}, context);
|
||||
try {
|
||||
step.output = await Promise.race([executePromise, timeoutPromise]);
|
||||
} finally {
|
||||
if (timeoutId) clearTimeout(timeoutId);
|
||||
}
|
||||
}
|
||||
|
||||
step.status = 'completed';
|
||||
step.completedAt = new Date().toISOString();
|
||||
step.duration = this.calculateDuration(step.startedAt, step.completedAt);
|
||||
this.config.onStepComplete?.(step, context.flow);
|
||||
this.updateStepMetrics(step.name, true, step.duration);
|
||||
|
||||
return step;
|
||||
} catch (error) {
|
||||
lastError = error instanceof Error ? error : new Error(String(error));
|
||||
step.retryCount++;
|
||||
|
||||
if (stepDef?.retryable !== false && step.retryCount <= maxRetries) {
|
||||
await this.delay(retryDelay * step.retryCount);
|
||||
} else {
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
step.status = 'failed';
|
||||
step.error = lastError?.message || 'Unknown error';
|
||||
step.completedAt = new Date().toISOString();
|
||||
step.duration = this.calculateDuration(step.startedAt, step.completedAt);
|
||||
this.config.onStepError?.(step, lastError || new Error('Unknown error'), context.flow);
|
||||
this.updateStepMetrics(step.name, false, step.duration);
|
||||
|
||||
return step;
|
||||
}
|
||||
|
||||
getFlow(flowId: string): ExecutionFlow | undefined {
|
||||
return this.flows.get(flowId);
|
||||
}
|
||||
|
||||
getFlowSummary(flowId: string): FlowSummary | null {
|
||||
const flow = this.flows.get(flowId);
|
||||
if (!flow) return null;
|
||||
|
||||
const completedSteps = flow.steps.filter(
|
||||
(s) => s.status === 'completed' || s.status === 'skipped'
|
||||
).length;
|
||||
|
||||
const currentStep =
|
||||
flow.currentStepIndex >= 0 ? flow.steps[flow.currentStepIndex]?.name : undefined;
|
||||
|
||||
return {
|
||||
id: flow.id,
|
||||
skillName: flow.skillName,
|
||||
status: flow.status,
|
||||
progress: flow.steps.length > 0 ? (completedSteps / flow.steps.length) * 100 : 0,
|
||||
currentStep,
|
||||
startedAt: flow.startedAt,
|
||||
completedAt: flow.completedAt,
|
||||
totalDuration: flow.totalDuration,
|
||||
stepsCompleted: completedSteps,
|
||||
totalSteps: flow.steps.length,
|
||||
mode: flow.mode,
|
||||
};
|
||||
}
|
||||
|
||||
getAllFlowSummaries(): FlowSummary[] {
|
||||
return [...this.flows.keys()]
|
||||
.map((id) => this.getFlowSummary(id))
|
||||
.filter((s): s is FlowSummary => s !== null);
|
||||
}
|
||||
|
||||
getMetrics(): FlowMetrics {
|
||||
return { ...this.metrics };
|
||||
}
|
||||
|
||||
cancelFlow(flowId: string): boolean {
|
||||
const flow = this.flows.get(flowId);
|
||||
if (!flow || flow.status !== 'running') return false;
|
||||
|
||||
flow.status = 'failed';
|
||||
flow.completedAt = new Date().toISOString();
|
||||
|
||||
const currentStep = flow.steps[flow.currentStepIndex];
|
||||
if (currentStep && currentStep.status === 'running') {
|
||||
currentStep.status = 'failed';
|
||||
currentStep.error = 'Cancelled';
|
||||
currentStep.completedAt = new Date().toISOString();
|
||||
}
|
||||
|
||||
return true;
|
||||
}
|
||||
|
||||
clearCompletedFlows(): number {
|
||||
let cleared = 0;
|
||||
for (const [id, flow] of this.flows) {
|
||||
if (flow.status === 'completed' || flow.status === 'failed') {
|
||||
this.flows.delete(id);
|
||||
cleared++;
|
||||
}
|
||||
}
|
||||
return cleared;
|
||||
}
|
||||
|
||||
private calculateDuration(start?: string, end?: string): number {
|
||||
if (!start || !end) return 0;
|
||||
return new Date(end).getTime() - new Date(start).getTime();
|
||||
}
|
||||
|
||||
private updateAverageDuration(duration: number): void {
|
||||
const completedCount = this.metrics.completedFlows;
|
||||
this.metrics.averageDuration =
|
||||
(this.metrics.averageDuration * (completedCount - 1) + duration) / completedCount;
|
||||
}
|
||||
|
||||
private updateStepMetrics(stepName: string, success: boolean, duration: number): void {
|
||||
const existing = this.metrics.stepMetrics.get(stepName) || {
|
||||
executionCount: 0,
|
||||
successCount: 0,
|
||||
failureCount: 0,
|
||||
averageDuration: 0,
|
||||
};
|
||||
|
||||
existing.executionCount++;
|
||||
if (success) {
|
||||
existing.successCount++;
|
||||
} else {
|
||||
existing.failureCount++;
|
||||
}
|
||||
existing.averageDuration =
|
||||
(existing.averageDuration * (existing.executionCount - 1) + duration) /
|
||||
existing.executionCount;
|
||||
|
||||
this.metrics.stepMetrics.set(stepName, existing);
|
||||
}
|
||||
|
||||
private delay(ms: number): Promise<void> {
|
||||
return new Promise((resolve) => setTimeout(resolve, ms));
|
||||
}
|
||||
}
|
||||
|
||||
export function createExecutionManager(config?: ExecutionFlowConfig): ExecutionManager {
|
||||
return new ExecutionManager(config);
|
||||
}
|
||||
@@ -0,0 +1,257 @@
|
||||
import { existsSync, readFileSync } from 'node:fs';
|
||||
import { join } from 'node:path';
|
||||
import { homedir } from 'node:os';
|
||||
import type { ConnectorMapping } from '../connectors/types.js';
|
||||
import { suggestMappingsFromMcp } from '../connectors/utils.js';
|
||||
|
||||
export type ExecutionMode = 'standalone' | 'enhanced';
|
||||
|
||||
export interface ModeDetectionResult {
|
||||
mode: ExecutionMode;
|
||||
availableServers: string[];
|
||||
missingServers: string[];
|
||||
capabilities: ModeCapabilities;
|
||||
connectorMappings: ConnectorMapping[];
|
||||
}
|
||||
|
||||
export interface ModeCapabilities {
|
||||
canAccessCRM: boolean;
|
||||
canSendEmails: boolean;
|
||||
canAccessCalendar: boolean;
|
||||
canAccessDocs: boolean;
|
||||
canQueryData: boolean;
|
||||
canEnrichData: boolean;
|
||||
canSendNotifications: boolean;
|
||||
canUseAI: boolean;
|
||||
hasChat: boolean;
|
||||
hasStorage: boolean;
|
||||
hasSearch: boolean;
|
||||
hasAnalytics: boolean;
|
||||
}
|
||||
|
||||
export interface ExecutionModeConfig {
|
||||
requiredServers?: string[];
|
||||
optionalServers?: string[];
|
||||
mcpConfigPaths?: string[];
|
||||
fallbackToStandalone?: boolean;
|
||||
}
|
||||
|
||||
const DEFAULT_MCP_CONFIG_PATHS = [
|
||||
join(homedir(), '.mcp.json'),
|
||||
join(homedir(), '.config', 'claude', 'mcp.json'),
|
||||
'.mcp.json',
|
||||
'mcp.json',
|
||||
];
|
||||
|
||||
const CAPABILITY_SERVERS: Record<keyof ModeCapabilities, string[]> = {
|
||||
canAccessCRM: ['salesforce', 'hubspot', 'pipedrive', 'zoho'],
|
||||
canSendEmails: ['gmail', 'outlook', 'sendgrid', 'mailgun', 'ses'],
|
||||
canAccessCalendar: ['google-calendar', 'outlook', 'calendly'],
|
||||
canAccessDocs: ['notion', 'confluence', 'google-docs', 'coda'],
|
||||
canQueryData: ['postgres', 'mysql', 'bigquery', 'snowflake', 'supabase', 'mongodb'],
|
||||
canEnrichData: ['clearbit', 'zoominfo', 'apollo', 'hunter'],
|
||||
canSendNotifications: ['slack', 'teams', 'discord', 'pagerduty', 'opsgenie'],
|
||||
canUseAI: ['openai', 'anthropic', 'ollama', 'huggingface'],
|
||||
hasChat: ['slack', 'teams', 'discord'],
|
||||
hasStorage: ['s3', 'gcs', 'dropbox', 'drive', 'box'],
|
||||
hasSearch: ['glean', 'elastic', 'algolia', 'typesense'],
|
||||
hasAnalytics: ['mixpanel', 'amplitude', 'posthog', 'segment'],
|
||||
};
|
||||
|
||||
export function detectExecutionMode(config: ExecutionModeConfig = {}): ModeDetectionResult {
|
||||
const { requiredServers = [], optionalServers = [], mcpConfigPaths, fallbackToStandalone = true } = config;
|
||||
|
||||
const configPaths = mcpConfigPaths || DEFAULT_MCP_CONFIG_PATHS;
|
||||
const availableServers = detectMcpServers(configPaths);
|
||||
|
||||
const missingRequired = requiredServers.filter(
|
||||
(server) => !availableServers.some((s) => s.toLowerCase().includes(server.toLowerCase()))
|
||||
);
|
||||
|
||||
const capabilities = detectCapabilities(availableServers);
|
||||
const connectorMappings = suggestMappingsFromMcp(availableServers);
|
||||
|
||||
let mode: ExecutionMode = 'standalone';
|
||||
if (missingRequired.length === 0 && availableServers.length > 0) {
|
||||
mode = 'enhanced';
|
||||
} else if (missingRequired.length > 0 && !fallbackToStandalone) {
|
||||
throw new Error(`Missing required MCP servers: ${missingRequired.join(', ')}`);
|
||||
}
|
||||
|
||||
const missingOptional = optionalServers.filter(
|
||||
(server) => !availableServers.some((s) => s.toLowerCase().includes(server.toLowerCase()))
|
||||
);
|
||||
|
||||
return {
|
||||
mode,
|
||||
availableServers,
|
||||
missingServers: [...missingRequired, ...missingOptional],
|
||||
capabilities,
|
||||
connectorMappings,
|
||||
};
|
||||
}
|
||||
|
||||
function detectMcpServers(configPaths: string[]): string[] {
|
||||
const servers: string[] = [];
|
||||
|
||||
for (const configPath of configPaths) {
|
||||
try {
|
||||
const fullPath = configPath.startsWith('~')
|
||||
? configPath.replace('~', process.env.HOME || '')
|
||||
: configPath;
|
||||
|
||||
if (existsSync(fullPath)) {
|
||||
const content = readFileSync(fullPath, 'utf-8');
|
||||
const config = JSON.parse(content);
|
||||
|
||||
if (config.mcpServers) {
|
||||
servers.push(...Object.keys(config.mcpServers));
|
||||
}
|
||||
|
||||
if (config.servers) {
|
||||
servers.push(...Object.keys(config.servers));
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
return [...new Set(servers)];
|
||||
}
|
||||
|
||||
function detectCapabilities(servers: string[]): ModeCapabilities {
|
||||
const serverLower = servers.map((s) => s.toLowerCase());
|
||||
|
||||
const capabilities: ModeCapabilities = {
|
||||
canAccessCRM: false,
|
||||
canSendEmails: false,
|
||||
canAccessCalendar: false,
|
||||
canAccessDocs: false,
|
||||
canQueryData: false,
|
||||
canEnrichData: false,
|
||||
canSendNotifications: false,
|
||||
canUseAI: false,
|
||||
hasChat: false,
|
||||
hasStorage: false,
|
||||
hasSearch: false,
|
||||
hasAnalytics: false,
|
||||
};
|
||||
|
||||
for (const [capability, keywords] of Object.entries(CAPABILITY_SERVERS)) {
|
||||
for (const keyword of keywords) {
|
||||
if (serverLower.some((server) => server.includes(keyword))) {
|
||||
capabilities[capability as keyof ModeCapabilities] = true;
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return capabilities;
|
||||
}
|
||||
|
||||
export function getModeDescription(result: ModeDetectionResult): string {
|
||||
const lines: string[] = [];
|
||||
|
||||
lines.push(`Mode: ${result.mode.toUpperCase()}`);
|
||||
lines.push('');
|
||||
|
||||
if (result.availableServers.length > 0) {
|
||||
lines.push(`Available MCP Servers (${result.availableServers.length}):`);
|
||||
for (const server of result.availableServers.slice(0, 10)) {
|
||||
lines.push(` - ${server}`);
|
||||
}
|
||||
if (result.availableServers.length > 10) {
|
||||
lines.push(` ... and ${result.availableServers.length - 10} more`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
if (result.missingServers.length > 0) {
|
||||
lines.push(`Missing Servers:`);
|
||||
for (const server of result.missingServers) {
|
||||
lines.push(` - ${server}`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
lines.push('Capabilities:');
|
||||
const capabilityLabels: Record<keyof ModeCapabilities, string> = {
|
||||
canAccessCRM: 'CRM Access',
|
||||
canSendEmails: 'Email',
|
||||
canAccessCalendar: 'Calendar',
|
||||
canAccessDocs: 'Documents',
|
||||
canQueryData: 'Data Queries',
|
||||
canEnrichData: 'Data Enrichment',
|
||||
canSendNotifications: 'Notifications',
|
||||
canUseAI: 'AI Services',
|
||||
hasChat: 'Chat',
|
||||
hasStorage: 'Storage',
|
||||
hasSearch: 'Search',
|
||||
hasAnalytics: 'Analytics',
|
||||
};
|
||||
|
||||
for (const [key, label] of Object.entries(capabilityLabels)) {
|
||||
const enabled = result.capabilities[key as keyof ModeCapabilities];
|
||||
lines.push(` ${enabled ? '✓' : '✗'} ${label}`);
|
||||
}
|
||||
|
||||
if (result.connectorMappings.length > 0) {
|
||||
lines.push('');
|
||||
lines.push('Suggested Connector Mappings:');
|
||||
for (const mapping of result.connectorMappings.slice(0, 5)) {
|
||||
lines.push(` ${mapping.placeholder} → ${mapping.tool}`);
|
||||
}
|
||||
}
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
export function requireEnhancedMode(result: ModeDetectionResult): void {
|
||||
if (result.mode !== 'enhanced') {
|
||||
throw new Error(
|
||||
`This skill requires enhanced mode with MCP servers. Missing: ${result.missingServers.join(', ')}`
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
export function requireCapability(
|
||||
result: ModeDetectionResult,
|
||||
capability: keyof ModeCapabilities
|
||||
): void {
|
||||
if (!result.capabilities[capability]) {
|
||||
throw new Error(`This skill requires the ${capability} capability which is not available.`);
|
||||
}
|
||||
}
|
||||
|
||||
export function getStandaloneAlternative(capability: keyof ModeCapabilities): string {
|
||||
const alternatives: Record<keyof ModeCapabilities, string> = {
|
||||
canAccessCRM: 'Use a local JSON file to store contact information',
|
||||
canSendEmails: 'Output email content to the terminal for manual sending',
|
||||
canAccessCalendar: 'Use a local iCal file for scheduling',
|
||||
canAccessDocs: 'Use local markdown files for documentation',
|
||||
canQueryData: 'Use a local SQLite database or JSON files',
|
||||
canEnrichData: 'Skip enrichment or use cached data',
|
||||
canSendNotifications: 'Output notifications to the terminal',
|
||||
canUseAI: 'Use simpler rule-based logic or skip AI features',
|
||||
hasChat: 'Output messages to the terminal',
|
||||
hasStorage: 'Use the local filesystem',
|
||||
hasSearch: 'Use grep or local file search',
|
||||
hasAnalytics: 'Skip analytics or use local logging',
|
||||
};
|
||||
|
||||
return alternatives[capability];
|
||||
}
|
||||
|
||||
export function createModeAwareExecutor<T>(
|
||||
enhancedFn: () => Promise<T>,
|
||||
standaloneFn: () => Promise<T>,
|
||||
modeResult: ModeDetectionResult
|
||||
): () => Promise<T> {
|
||||
return async () => {
|
||||
if (modeResult.mode === 'enhanced') {
|
||||
return enhancedFn();
|
||||
}
|
||||
return standaloneFn();
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,106 @@
|
||||
import { z } from 'zod';
|
||||
|
||||
export const ExecutionStepStatusSchema = z.enum([
|
||||
'pending',
|
||||
'running',
|
||||
'completed',
|
||||
'failed',
|
||||
'skipped',
|
||||
]);
|
||||
|
||||
export type ExecutionStepStatus = z.infer<typeof ExecutionStepStatusSchema>;
|
||||
|
||||
export const ExecutionStepSchema = z.object({
|
||||
id: z.string(),
|
||||
name: z.string(),
|
||||
description: z.string().optional(),
|
||||
status: ExecutionStepStatusSchema.default('pending'),
|
||||
startedAt: z.string().datetime().optional(),
|
||||
completedAt: z.string().datetime().optional(),
|
||||
duration: z.number().optional(),
|
||||
input: z.record(z.unknown()).optional(),
|
||||
output: z.record(z.unknown()).optional(),
|
||||
error: z.string().optional(),
|
||||
retryCount: z.number().default(0),
|
||||
metadata: z.record(z.unknown()).optional(),
|
||||
});
|
||||
|
||||
export type ExecutionStep = z.infer<typeof ExecutionStepSchema>;
|
||||
|
||||
export const ExecutionFlowSchema = z.object({
|
||||
id: z.string(),
|
||||
skillName: z.string(),
|
||||
version: z.number().default(1),
|
||||
steps: z.array(ExecutionStepSchema),
|
||||
currentStepIndex: z.number().default(-1),
|
||||
status: ExecutionStepStatusSchema.default('pending'),
|
||||
startedAt: z.string().datetime().optional(),
|
||||
completedAt: z.string().datetime().optional(),
|
||||
totalDuration: z.number().optional(),
|
||||
context: z.record(z.unknown()).optional(),
|
||||
mode: z.enum(['standalone', 'enhanced']).default('standalone'),
|
||||
mcpServers: z.array(z.string()).optional(),
|
||||
});
|
||||
|
||||
export type ExecutionFlow = z.infer<typeof ExecutionFlowSchema>;
|
||||
|
||||
export interface ExecutionFlowConfig {
|
||||
maxRetries?: number;
|
||||
retryDelay?: number;
|
||||
timeout?: number;
|
||||
onStepStart?: (step: ExecutionStep, flow: ExecutionFlow) => void;
|
||||
onStepComplete?: (step: ExecutionStep, flow: ExecutionFlow) => void;
|
||||
onStepError?: (step: ExecutionStep, error: Error, flow: ExecutionFlow) => void;
|
||||
onFlowComplete?: (flow: ExecutionFlow) => void;
|
||||
}
|
||||
|
||||
export interface StepDefinition {
|
||||
name: string;
|
||||
description?: string;
|
||||
execute: (
|
||||
input: Record<string, unknown>,
|
||||
context: ExecutionContext
|
||||
) => Promise<Record<string, unknown>>;
|
||||
rollback?: (context: ExecutionContext) => Promise<void>;
|
||||
condition?: (context: ExecutionContext) => boolean;
|
||||
retryable?: boolean;
|
||||
timeout?: number;
|
||||
}
|
||||
|
||||
export interface ExecutionContext {
|
||||
flow: ExecutionFlow;
|
||||
stepIndex: number;
|
||||
previousOutput?: Record<string, unknown>;
|
||||
mcpTools?: string[];
|
||||
isEnhanced: boolean;
|
||||
}
|
||||
|
||||
export interface FlowSummary {
|
||||
id: string;
|
||||
skillName: string;
|
||||
status: ExecutionStepStatus;
|
||||
progress: number;
|
||||
currentStep?: string;
|
||||
startedAt?: string;
|
||||
completedAt?: string;
|
||||
totalDuration?: number;
|
||||
stepsCompleted: number;
|
||||
totalSteps: number;
|
||||
mode: 'standalone' | 'enhanced';
|
||||
}
|
||||
|
||||
export interface FlowMetrics {
|
||||
totalFlows: number;
|
||||
completedFlows: number;
|
||||
failedFlows: number;
|
||||
averageDuration: number;
|
||||
stepMetrics: Map<
|
||||
string,
|
||||
{
|
||||
executionCount: number;
|
||||
successCount: number;
|
||||
failureCount: number;
|
||||
averageDuration: number;
|
||||
}
|
||||
>;
|
||||
}
|
||||
@@ -89,3 +89,18 @@ export * from './profiles/index.js';
|
||||
|
||||
// Coding Guidelines System
|
||||
export * from './guidelines/index.js';
|
||||
|
||||
// Skill Tree (Hierarchical Taxonomy - Phase 21)
|
||||
export * from './tree/index.js';
|
||||
|
||||
// Reasoning Engine (LLM-based Tree Search - Phase 21)
|
||||
export * from './reasoning/index.js';
|
||||
|
||||
// Connectors (Tool-Agnostic Placeholders - Phase 21)
|
||||
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';
|
||||
|
||||
@@ -0,0 +1,194 @@
|
||||
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
|
||||
import { WellKnownProvider, generateWellKnownIndex, generateWellKnownStructure, calculateBaseSkillsUrl } from '../wellknown.js';
|
||||
import { existsSync, rmSync, readFileSync } from 'node:fs';
|
||||
import { join } from 'node:path';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { randomUUID } from 'node:crypto';
|
||||
|
||||
describe('WellKnownProvider', () => {
|
||||
const provider = new WellKnownProvider();
|
||||
|
||||
describe('matches', () => {
|
||||
it('should match https URLs not on github/gitlab/bitbucket', () => {
|
||||
expect(provider.matches('https://example.com')).toBe(true);
|
||||
expect(provider.matches('https://skills.vercel.app')).toBe(true);
|
||||
expect(provider.matches('https://my-skills.com/api')).toBe(true);
|
||||
});
|
||||
|
||||
it('should not match github.com URLs', () => {
|
||||
expect(provider.matches('https://github.com/owner/repo')).toBe(false);
|
||||
});
|
||||
|
||||
it('should not match gitlab.com URLs', () => {
|
||||
expect(provider.matches('https://gitlab.com/owner/repo')).toBe(false);
|
||||
});
|
||||
|
||||
it('should not match bitbucket.org URLs', () => {
|
||||
expect(provider.matches('https://bitbucket.org/owner/repo')).toBe(false);
|
||||
});
|
||||
|
||||
it('should not match local paths', () => {
|
||||
expect(provider.matches('./my-skills')).toBe(false);
|
||||
expect(provider.matches('/absolute/path')).toBe(false);
|
||||
expect(provider.matches('~/home/skills')).toBe(false);
|
||||
});
|
||||
|
||||
it('should not match shorthand GitHub format', () => {
|
||||
expect(provider.matches('owner/repo')).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('parseSource', () => {
|
||||
it('should parse URL hostname and path', () => {
|
||||
const result = provider.parseSource('https://example.com/api');
|
||||
expect(result).toEqual({ owner: 'example.com', repo: 'api' });
|
||||
});
|
||||
|
||||
it('should handle root URLs', () => {
|
||||
const result = provider.parseSource('https://skills.example.com');
|
||||
expect(result).toEqual({ owner: 'skills.example.com', repo: 'skills' });
|
||||
});
|
||||
|
||||
it('should return null for invalid URLs', () => {
|
||||
const result = provider.parseSource('not-a-url');
|
||||
expect(result).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe('type and name', () => {
|
||||
it('should have correct type', () => {
|
||||
expect(provider.type).toBe('wellknown');
|
||||
});
|
||||
|
||||
it('should have correct name', () => {
|
||||
expect(provider.name).toBe('Well-Known');
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('calculateBaseSkillsUrl', () => {
|
||||
it('should handle index.json URL correctly', () => {
|
||||
const result = calculateBaseSkillsUrl('https://example.com/.well-known/skills/index.json');
|
||||
expect(result).toBe('https://example.com/.well-known/skills');
|
||||
});
|
||||
|
||||
it('should handle skills.json URL correctly without duplicating .well-known', () => {
|
||||
const result = calculateBaseSkillsUrl('https://example.com/.well-known/skills.json');
|
||||
expect(result).toBe('https://example.com/.well-known/skills');
|
||||
});
|
||||
|
||||
it('should handle nested paths with index.json', () => {
|
||||
const result = calculateBaseSkillsUrl('https://cdn.example.com/v1/.well-known/skills/index.json');
|
||||
expect(result).toBe('https://cdn.example.com/v1/.well-known/skills');
|
||||
});
|
||||
|
||||
it('should handle nested paths with skills.json', () => {
|
||||
const result = calculateBaseSkillsUrl('https://cdn.example.com/v1/.well-known/skills.json');
|
||||
expect(result).toBe('https://cdn.example.com/v1/.well-known/skills');
|
||||
});
|
||||
});
|
||||
|
||||
describe('generateWellKnownIndex', () => {
|
||||
it('should generate valid index structure', () => {
|
||||
const skills = [
|
||||
{ name: 'test-skill', description: 'A test skill', files: ['SKILL.md', 'README.md'] },
|
||||
{ name: 'another-skill', description: 'Another skill', files: ['SKILL.md'] },
|
||||
];
|
||||
|
||||
const index = generateWellKnownIndex(skills);
|
||||
|
||||
expect(index.version).toBe('1.0');
|
||||
expect(index.skills).toHaveLength(2);
|
||||
expect(index.skills[0]).toEqual({
|
||||
name: 'test-skill',
|
||||
description: 'A test skill',
|
||||
files: ['SKILL.md', 'README.md'],
|
||||
});
|
||||
expect(index.skills[1]).toEqual({
|
||||
name: 'another-skill',
|
||||
description: 'Another skill',
|
||||
files: ['SKILL.md'],
|
||||
});
|
||||
});
|
||||
|
||||
it('should handle empty skills array', () => {
|
||||
const index = generateWellKnownIndex([]);
|
||||
expect(index.version).toBe('1.0');
|
||||
expect(index.skills).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe('generateWellKnownStructure', () => {
|
||||
let tempDir: string;
|
||||
|
||||
beforeEach(() => {
|
||||
tempDir = join(tmpdir(), `skillkit-test-${randomUUID()}`);
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
if (existsSync(tempDir)) {
|
||||
rmSync(tempDir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
it('should create well-known directory structure', () => {
|
||||
const skills = [
|
||||
{
|
||||
name: 'test-skill',
|
||||
description: 'A test skill',
|
||||
content: '---\nname: test-skill\ndescription: A test skill\n---\n\n# Test Skill\n\nContent here.',
|
||||
},
|
||||
];
|
||||
|
||||
const result = generateWellKnownStructure(tempDir, skills);
|
||||
|
||||
expect(existsSync(join(tempDir, '.well-known', 'skills'))).toBe(true);
|
||||
expect(existsSync(result.indexPath)).toBe(true);
|
||||
expect(result.skillPaths).toContain(join(tempDir, '.well-known', 'skills', 'test-skill', 'SKILL.md'));
|
||||
|
||||
const index = JSON.parse(readFileSync(result.indexPath, 'utf-8'));
|
||||
expect(index.skills[0].name).toBe('test-skill');
|
||||
expect(index.skills[0].files).toContain('SKILL.md');
|
||||
});
|
||||
|
||||
it('should include additional files', () => {
|
||||
const skills = [
|
||||
{
|
||||
name: 'test-skill',
|
||||
description: 'Test',
|
||||
content: '# Test',
|
||||
additionalFiles: {
|
||||
'README.md': '# README',
|
||||
'config.json': '{"key": "value"}',
|
||||
},
|
||||
},
|
||||
];
|
||||
|
||||
const result = generateWellKnownStructure(tempDir, skills);
|
||||
|
||||
expect(result.skillPaths).toContain(join(tempDir, '.well-known', 'skills', 'test-skill', 'README.md'));
|
||||
expect(result.skillPaths).toContain(join(tempDir, '.well-known', 'skills', 'test-skill', 'config.json'));
|
||||
|
||||
const readme = readFileSync(join(tempDir, '.well-known', 'skills', 'test-skill', 'README.md'), 'utf-8');
|
||||
expect(readme).toBe('# README');
|
||||
|
||||
const index = JSON.parse(readFileSync(result.indexPath, 'utf-8'));
|
||||
expect(index.skills[0].files).toContain('README.md');
|
||||
expect(index.skills[0].files).toContain('config.json');
|
||||
});
|
||||
|
||||
it('should handle multiple skills', () => {
|
||||
const skills = [
|
||||
{ name: 'skill-one', description: 'First', content: '# Skill One' },
|
||||
{ name: 'skill-two', description: 'Second', content: '# Skill Two' },
|
||||
];
|
||||
|
||||
const result = generateWellKnownStructure(tempDir, skills);
|
||||
|
||||
expect(existsSync(join(tempDir, '.well-known', 'skills', 'skill-one', 'SKILL.md'))).toBe(true);
|
||||
expect(existsSync(join(tempDir, '.well-known', 'skills', 'skill-two', 'SKILL.md'))).toBe(true);
|
||||
|
||||
const index = JSON.parse(readFileSync(result.indexPath, 'utf-8'));
|
||||
expect(index.skills).toHaveLength(2);
|
||||
});
|
||||
});
|
||||
@@ -4,17 +4,20 @@ import { GitHubProvider } from './github.js';
|
||||
import { GitLabProvider } from './gitlab.js';
|
||||
import { BitbucketProvider } from './bitbucket.js';
|
||||
import { LocalProvider } from './local.js';
|
||||
import { WellKnownProvider } from './wellknown.js';
|
||||
|
||||
export * from './base.js';
|
||||
export * from './github.js';
|
||||
export * from './gitlab.js';
|
||||
export * from './bitbucket.js';
|
||||
export * from './local.js';
|
||||
export * from './wellknown.js';
|
||||
|
||||
const providers: GitProviderAdapter[] = [
|
||||
new LocalProvider(),
|
||||
new GitLabProvider(),
|
||||
new BitbucketProvider(),
|
||||
new WellKnownProvider(),
|
||||
new GitHubProvider(),
|
||||
];
|
||||
|
||||
|
||||
@@ -0,0 +1,248 @@
|
||||
import { existsSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
|
||||
import { join, basename, resolve, sep } from 'node:path';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { randomUUID } from 'node:crypto';
|
||||
import type { GitProviderAdapter, CloneOptions } from './base.js';
|
||||
import { isGitUrl, isLocalPath } from './base.js';
|
||||
import type { GitProvider, CloneResult } from '../types.js';
|
||||
|
||||
function sanitizeSkillName(name: string): string | null {
|
||||
if (!name || typeof name !== 'string') return null;
|
||||
const base = basename(name);
|
||||
if (base !== name || name.includes('..') || name.includes('/') || name.includes('\\')) {
|
||||
return null;
|
||||
}
|
||||
if (!/^[a-zA-Z0-9._-]+$/.test(name)) {
|
||||
return null;
|
||||
}
|
||||
return name;
|
||||
}
|
||||
|
||||
export interface WellKnownSkill {
|
||||
name: string;
|
||||
description?: string;
|
||||
files: string[];
|
||||
}
|
||||
|
||||
export interface WellKnownIndex {
|
||||
version?: string;
|
||||
skills: WellKnownSkill[];
|
||||
}
|
||||
|
||||
export class WellKnownProvider implements GitProviderAdapter {
|
||||
readonly type: GitProvider = 'wellknown';
|
||||
readonly name = 'Well-Known';
|
||||
readonly baseUrl = '';
|
||||
|
||||
parseSource(source: string): { owner: string; repo: string; subpath?: string } | null {
|
||||
try {
|
||||
const url = new URL(source);
|
||||
return { owner: url.hostname, repo: url.pathname.replace(/^\//, '') || 'skills' };
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
matches(source: string): boolean {
|
||||
if (isLocalPath(source)) return false;
|
||||
if (!isGitUrl(source)) return false;
|
||||
if (source.includes('github.com')) return false;
|
||||
if (source.includes('gitlab.com')) return false;
|
||||
if (source.includes('bitbucket.org')) return false;
|
||||
|
||||
try {
|
||||
new URL(source);
|
||||
return true;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
getCloneUrl(_owner: string, _repo: string): string {
|
||||
return '';
|
||||
}
|
||||
|
||||
getSshUrl(_owner: string, _repo: string): string {
|
||||
return '';
|
||||
}
|
||||
|
||||
async clone(source: string, _targetDir: string, _options: CloneOptions = {}): Promise<CloneResult> {
|
||||
const tempDir = join(tmpdir(), `skillkit-wellknown-${randomUUID()}`);
|
||||
|
||||
try {
|
||||
mkdirSync(tempDir, { recursive: true });
|
||||
|
||||
const baseUrl = source.replace(/\/$/, '');
|
||||
const indexUrls = [
|
||||
`${baseUrl}/.well-known/skills/index.json`,
|
||||
`${baseUrl}/.well-known/skills.json`,
|
||||
];
|
||||
|
||||
let index: WellKnownIndex | null = null;
|
||||
let foundUrl = '';
|
||||
|
||||
for (const url of indexUrls) {
|
||||
try {
|
||||
const response = await fetch(url);
|
||||
if (response.ok) {
|
||||
index = await response.json() as WellKnownIndex;
|
||||
foundUrl = url;
|
||||
break;
|
||||
}
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
if (!index || !index.skills || index.skills.length === 0) {
|
||||
return {
|
||||
success: false,
|
||||
error: `No skills found at ${baseUrl}/.well-known/skills/index.json`,
|
||||
};
|
||||
}
|
||||
|
||||
const skills: string[] = [];
|
||||
const discoveredSkills: Array<{ name: string; dirName: string; path: string }> = [];
|
||||
const baseSkillsUrl = calculateBaseSkillsUrl(foundUrl);
|
||||
|
||||
for (const skill of index.skills) {
|
||||
const safeName = sanitizeSkillName(skill.name);
|
||||
if (!safeName) {
|
||||
continue;
|
||||
}
|
||||
|
||||
const skillDir = join(tempDir, safeName);
|
||||
const resolvedSkillDir = resolve(skillDir);
|
||||
const resolvedTempDir = resolve(tempDir);
|
||||
|
||||
if (!resolvedSkillDir.startsWith(resolvedTempDir + sep) && resolvedSkillDir !== resolvedTempDir) {
|
||||
continue;
|
||||
}
|
||||
|
||||
mkdirSync(skillDir, { recursive: true });
|
||||
|
||||
let hasSkillMd = false;
|
||||
|
||||
for (const file of skill.files) {
|
||||
const fileUrl = `${baseSkillsUrl}/${encodeURIComponent(skill.name)}/${encodeURIComponent(file)}`;
|
||||
try {
|
||||
const response = await fetch(fileUrl);
|
||||
if (response.ok) {
|
||||
const content = await response.text();
|
||||
const safeFileName = basename(file);
|
||||
writeFileSync(join(skillDir, safeFileName), content);
|
||||
|
||||
if (file === 'SKILL.md' || file.endsWith('/SKILL.md')) {
|
||||
hasSkillMd = true;
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
if (hasSkillMd) {
|
||||
skills.push(safeName);
|
||||
discoveredSkills.push({
|
||||
name: safeName,
|
||||
dirName: safeName,
|
||||
path: skillDir,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
if (skills.length === 0) {
|
||||
rmSync(tempDir, { recursive: true, force: true });
|
||||
return {
|
||||
success: false,
|
||||
error: 'No valid skills found (skills must contain SKILL.md)',
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
success: true,
|
||||
path: tempDir,
|
||||
tempRoot: tempDir,
|
||||
skills,
|
||||
discoveredSkills,
|
||||
};
|
||||
} catch (error) {
|
||||
if (existsSync(tempDir)) {
|
||||
rmSync(tempDir, { recursive: true, force: true });
|
||||
}
|
||||
|
||||
const message = error instanceof Error ? error.message : String(error);
|
||||
return { success: false, error: `Failed to fetch skills: ${message}` };
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export function calculateBaseSkillsUrl(foundUrl: string): string {
|
||||
return foundUrl.endsWith('/index.json')
|
||||
? foundUrl.replace('/index.json', '')
|
||||
: foundUrl.replace('/skills.json', '/skills');
|
||||
}
|
||||
|
||||
export function generateWellKnownIndex(skills: Array<{ name: string; description?: string; files: string[] }>): WellKnownIndex {
|
||||
return {
|
||||
version: '1.0',
|
||||
skills: skills.map(s => ({
|
||||
name: s.name,
|
||||
description: s.description,
|
||||
files: s.files,
|
||||
})),
|
||||
};
|
||||
}
|
||||
|
||||
export function generateWellKnownStructure(
|
||||
outputDir: string,
|
||||
skills: Array<{ name: string; description?: string; content: string; additionalFiles?: Record<string, string> }>
|
||||
): { indexPath: string; skillPaths: string[] } {
|
||||
const wellKnownDir = join(outputDir, '.well-known', 'skills');
|
||||
const resolvedWellKnownDir = resolve(wellKnownDir);
|
||||
mkdirSync(wellKnownDir, { recursive: true });
|
||||
|
||||
const indexSkills: WellKnownSkill[] = [];
|
||||
const skillPaths: string[] = [];
|
||||
|
||||
for (const skill of skills) {
|
||||
const safeName = sanitizeSkillName(skill.name);
|
||||
if (!safeName) {
|
||||
continue;
|
||||
}
|
||||
|
||||
const skillDir = join(wellKnownDir, safeName);
|
||||
const resolvedSkillDir = resolve(skillDir);
|
||||
|
||||
if (!resolvedSkillDir.startsWith(resolvedWellKnownDir + sep) && resolvedSkillDir !== resolvedWellKnownDir) {
|
||||
continue;
|
||||
}
|
||||
|
||||
mkdirSync(skillDir, { recursive: true });
|
||||
|
||||
writeFileSync(join(skillDir, 'SKILL.md'), skill.content);
|
||||
skillPaths.push(join(skillDir, 'SKILL.md'));
|
||||
|
||||
const files = ['SKILL.md'];
|
||||
|
||||
if (skill.additionalFiles) {
|
||||
for (const [filename, content] of Object.entries(skill.additionalFiles)) {
|
||||
writeFileSync(join(skillDir, filename), content);
|
||||
files.push(filename);
|
||||
skillPaths.push(join(skillDir, filename));
|
||||
}
|
||||
}
|
||||
|
||||
indexSkills.push({
|
||||
name: skill.name,
|
||||
description: skill.description,
|
||||
files,
|
||||
});
|
||||
}
|
||||
|
||||
const index = generateWellKnownIndex(indexSkills);
|
||||
const indexPath = join(wellKnownDir, 'index.json');
|
||||
writeFileSync(indexPath, JSON.stringify(index, null, 2));
|
||||
|
||||
return { indexPath, skillPaths };
|
||||
}
|
||||
@@ -0,0 +1,618 @@
|
||||
import type { SkillSummary, ProjectProfile } from '../recommend/types.js';
|
||||
import type { SkillTree, TreeNode } from '../tree/types.js';
|
||||
import { TreeGenerator } from '../tree/generator.js';
|
||||
import {
|
||||
type ReasoningConfig,
|
||||
type TreeSearchQuery,
|
||||
type TreeSearchResult,
|
||||
type TreeReasoningResult,
|
||||
type ExplainedRecommendation,
|
||||
type ExplainedMatch,
|
||||
type SearchPlan,
|
||||
type ReasoningCacheEntry,
|
||||
type ReasoningEngineStats,
|
||||
DEFAULT_REASONING_CONFIG,
|
||||
} from './types.js';
|
||||
import {
|
||||
buildSearchPlanPrompt,
|
||||
buildExplanationPrompt,
|
||||
extractJsonFromResponse,
|
||||
validateSearchPlan,
|
||||
} from './prompts.js';
|
||||
import { CATEGORY_TAXONOMY } from '../tree/types.js';
|
||||
|
||||
const CACHE_TTL_MS = 5 * 60 * 1000;
|
||||
const MAX_CACHE_SIZE = 100;
|
||||
|
||||
export class ReasoningEngine {
|
||||
private config: ReasoningConfig;
|
||||
private skillMap: Map<string, SkillSummary> = new Map();
|
||||
private tree: SkillTree | null = null;
|
||||
private cache: Map<string, ReasoningCacheEntry> = new Map();
|
||||
private stats: ReasoningEngineStats = {
|
||||
totalQueries: 0,
|
||||
cacheHits: 0,
|
||||
cacheMisses: 0,
|
||||
averageProcessingTimeMs: 0,
|
||||
averageResultsPerQuery: 0,
|
||||
};
|
||||
|
||||
constructor(config?: Partial<ReasoningConfig>) {
|
||||
this.config = { ...DEFAULT_REASONING_CONFIG, ...config };
|
||||
}
|
||||
|
||||
loadSkills(skills: SkillSummary[]): void {
|
||||
this.skillMap.clear();
|
||||
for (const skill of skills) {
|
||||
this.skillMap.set(skill.name, skill);
|
||||
}
|
||||
}
|
||||
|
||||
loadTree(tree: SkillTree): void {
|
||||
this.tree = tree;
|
||||
}
|
||||
|
||||
generateTree(skills: SkillSummary[]): void {
|
||||
const generator = new TreeGenerator();
|
||||
this.tree = generator.generateTree(skills);
|
||||
this.loadSkills(skills);
|
||||
}
|
||||
|
||||
async search(query: TreeSearchQuery): Promise<TreeReasoningResult> {
|
||||
const startTime = Date.now();
|
||||
this.stats.totalQueries++;
|
||||
|
||||
const cacheKey = this.getCacheKey(query);
|
||||
const cached = this.getFromCache(cacheKey);
|
||||
if (cached) {
|
||||
this.stats.cacheHits++;
|
||||
return {
|
||||
query: query.query,
|
||||
results: cached.results,
|
||||
exploredPaths: [],
|
||||
reasoning: 'Retrieved from cache',
|
||||
totalNodesVisited: 0,
|
||||
processingTimeMs: Date.now() - startTime,
|
||||
};
|
||||
}
|
||||
|
||||
this.stats.cacheMisses++;
|
||||
|
||||
const maxResults = query.maxResults ?? 10;
|
||||
const minConfidence = query.minConfidence ?? 30;
|
||||
|
||||
const plan = await this.createSearchPlan(query);
|
||||
|
||||
const results: TreeSearchResult[] = [];
|
||||
const exploredPaths: string[][] = [];
|
||||
let totalNodesVisited = 0;
|
||||
|
||||
if (this.tree) {
|
||||
const traversalResult = await this.traverseTree(query, plan);
|
||||
results.push(...traversalResult.results);
|
||||
exploredPaths.push(...traversalResult.exploredPaths);
|
||||
totalNodesVisited = traversalResult.nodesVisited;
|
||||
} else {
|
||||
const fallbackResults = this.fallbackSearch(query);
|
||||
results.push(...fallbackResults);
|
||||
}
|
||||
|
||||
const filteredResults = results
|
||||
.filter((r) => r.confidence >= minConfidence)
|
||||
.sort((a, b) => b.confidence - a.confidence)
|
||||
.slice(0, maxResults);
|
||||
|
||||
const processingTimeMs = Date.now() - startTime;
|
||||
|
||||
this.updateStats(processingTimeMs, filteredResults.length);
|
||||
|
||||
this.addToCache(cacheKey, filteredResults);
|
||||
|
||||
return {
|
||||
query: query.query,
|
||||
results: filteredResults,
|
||||
exploredPaths,
|
||||
reasoning: this.buildReasoningSummary(plan, filteredResults),
|
||||
totalNodesVisited,
|
||||
processingTimeMs,
|
||||
};
|
||||
}
|
||||
|
||||
async explain(
|
||||
skill: SkillSummary,
|
||||
score: number,
|
||||
profile: ProjectProfile
|
||||
): Promise<ExplainedRecommendation> {
|
||||
const treePath = this.getSkillPath(skill.name);
|
||||
|
||||
const explanation = await this.generateExplanation(skill, score, profile);
|
||||
|
||||
return {
|
||||
skill,
|
||||
score,
|
||||
reasoning: explanation,
|
||||
treePath,
|
||||
};
|
||||
}
|
||||
|
||||
async explainBatch(
|
||||
skills: Array<{ skill: SkillSummary; score: number }>,
|
||||
profile: ProjectProfile
|
||||
): Promise<ExplainedRecommendation[]> {
|
||||
const results: ExplainedRecommendation[] = [];
|
||||
|
||||
for (const { skill, score } of skills) {
|
||||
const explained = await this.explain(skill, score, profile);
|
||||
results.push(explained);
|
||||
}
|
||||
|
||||
return results;
|
||||
}
|
||||
|
||||
private async createSearchPlan(query: TreeSearchQuery): Promise<SearchPlan> {
|
||||
const categories = CATEGORY_TAXONOMY.map((c) => c.category);
|
||||
|
||||
if (this.config.provider === 'mock') {
|
||||
return this.mockSearchPlan(query.query, query.context);
|
||||
}
|
||||
|
||||
const prompt = buildSearchPlanPrompt(
|
||||
query.query,
|
||||
categories,
|
||||
query.context
|
||||
);
|
||||
|
||||
const response = await this.callLLM(prompt);
|
||||
|
||||
try {
|
||||
const data = extractJsonFromResponse(response);
|
||||
return validateSearchPlan(data);
|
||||
} catch {
|
||||
return this.mockSearchPlan(query.query, query.context);
|
||||
}
|
||||
}
|
||||
|
||||
private mockSearchPlan(query: string, context?: ProjectProfile): SearchPlan {
|
||||
const queryLower = query.toLowerCase();
|
||||
const keywords = queryLower
|
||||
.split(/\s+/)
|
||||
.filter((w) => w.length > 2);
|
||||
|
||||
const categoryScores: { category: string; score: number }[] = [];
|
||||
|
||||
for (const mapping of CATEGORY_TAXONOMY) {
|
||||
let score = 0;
|
||||
|
||||
for (const keyword of keywords) {
|
||||
if (mapping.category.toLowerCase().includes(keyword)) {
|
||||
score += 30;
|
||||
}
|
||||
|
||||
for (const tag of mapping.tags) {
|
||||
if (tag.includes(keyword) || keyword.includes(tag)) {
|
||||
score += 20;
|
||||
}
|
||||
}
|
||||
|
||||
for (const kw of mapping.keywords) {
|
||||
if (kw.includes(keyword) || keyword.includes(kw)) {
|
||||
score += 15;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (context) {
|
||||
for (const framework of context.stack.frameworks) {
|
||||
if (mapping.tags.includes(framework.name.toLowerCase())) {
|
||||
score += 10;
|
||||
}
|
||||
}
|
||||
|
||||
for (const language of context.stack.languages) {
|
||||
if (mapping.tags.includes(language.name.toLowerCase())) {
|
||||
score += 5;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (score > 0) {
|
||||
categoryScores.push({ category: mapping.category, score });
|
||||
}
|
||||
}
|
||||
|
||||
categoryScores.sort((a, b) => b.score - a.score);
|
||||
|
||||
const primaryCategories = categoryScores
|
||||
.slice(0, 3)
|
||||
.map((c) => c.category);
|
||||
const secondaryCategories = categoryScores
|
||||
.slice(3, 6)
|
||||
.map((c) => c.category);
|
||||
|
||||
const filters: SearchPlan['filters'] = {
|
||||
tags: keywords.filter((k) =>
|
||||
CATEGORY_TAXONOMY.some((m) => m.tags.includes(k))
|
||||
),
|
||||
frameworks: context?.stack.frameworks.map((f) => f.name) || [],
|
||||
languages: context?.stack.languages.map((l) => l.name) || [],
|
||||
};
|
||||
|
||||
return {
|
||||
primaryCategories: primaryCategories.length > 0 ? primaryCategories : ['Development'],
|
||||
secondaryCategories,
|
||||
keywords,
|
||||
filters,
|
||||
strategy: keywords.length <= 2 ? 'breadth-first' : 'targeted',
|
||||
};
|
||||
}
|
||||
|
||||
private async traverseTree(
|
||||
query: TreeSearchQuery,
|
||||
plan: SearchPlan
|
||||
): Promise<{
|
||||
results: TreeSearchResult[];
|
||||
exploredPaths: string[][];
|
||||
nodesVisited: number;
|
||||
}> {
|
||||
if (!this.tree) {
|
||||
return { results: [], exploredPaths: [], nodesVisited: 0 };
|
||||
}
|
||||
|
||||
const results: TreeSearchResult[] = [];
|
||||
const exploredPaths: string[][] = [];
|
||||
let nodesVisited = 0;
|
||||
|
||||
const relevantNodes = this.findRelevantNodes(plan);
|
||||
|
||||
for (const { node, path } of relevantNodes) {
|
||||
nodesVisited++;
|
||||
exploredPaths.push(path);
|
||||
|
||||
for (const skillName of node.skills) {
|
||||
const skill = this.skillMap.get(skillName);
|
||||
if (!skill) continue;
|
||||
|
||||
const matchResult = this.evaluateSkillMatch(query.query, skill, query.context);
|
||||
|
||||
if (matchResult.confidence >= (query.minConfidence ?? 30)) {
|
||||
results.push({
|
||||
skill,
|
||||
path,
|
||||
reasoning: matchResult.reasoning,
|
||||
confidence: matchResult.confidence,
|
||||
relevantSections: matchResult.relevantSections,
|
||||
matchedKeywords: matchResult.matchedKeywords,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return { results, exploredPaths, nodesVisited };
|
||||
}
|
||||
|
||||
private findRelevantNodes(
|
||||
plan: SearchPlan
|
||||
): Array<{ node: TreeNode; path: string[] }> {
|
||||
if (!this.tree) return [];
|
||||
|
||||
const relevant: Array<{ node: TreeNode; path: string[]; priority: number }> = [];
|
||||
|
||||
const traverse = (node: TreeNode, path: string[], priorityBoost: number) => {
|
||||
const nodeName = node.name.toLowerCase();
|
||||
|
||||
let priority = priorityBoost;
|
||||
|
||||
if (plan.primaryCategories.some((c) => c.toLowerCase() === nodeName)) {
|
||||
priority += 100;
|
||||
}
|
||||
|
||||
if (plan.secondaryCategories.some((c) => c.toLowerCase() === nodeName)) {
|
||||
priority += 50;
|
||||
}
|
||||
|
||||
for (const keyword of plan.keywords) {
|
||||
if (nodeName.includes(keyword) || keyword.includes(nodeName)) {
|
||||
priority += 25;
|
||||
}
|
||||
}
|
||||
|
||||
if (priority > 0 || node.depth === 0) {
|
||||
relevant.push({ node, path: [...path, node.name], priority });
|
||||
}
|
||||
|
||||
for (const child of node.children) {
|
||||
traverse(child, [...path, node.name], priority > 0 ? priority * 0.5 : 0);
|
||||
}
|
||||
};
|
||||
|
||||
traverse(this.tree.rootNode, [], 0);
|
||||
|
||||
relevant.sort((a, b) => b.priority - a.priority);
|
||||
|
||||
return relevant.slice(0, 20).map(({ node, path }) => ({ node, path }));
|
||||
}
|
||||
|
||||
private evaluateSkillMatch(
|
||||
query: string,
|
||||
skill: SkillSummary,
|
||||
context?: ProjectProfile
|
||||
): {
|
||||
confidence: number;
|
||||
reasoning: string;
|
||||
relevantSections: string[];
|
||||
matchedKeywords: string[];
|
||||
} {
|
||||
const queryTerms = query.toLowerCase().split(/\s+/);
|
||||
const matchedKeywords: string[] = [];
|
||||
let confidence = 0;
|
||||
|
||||
const nameLower = skill.name.toLowerCase();
|
||||
for (const term of queryTerms) {
|
||||
if (nameLower.includes(term)) {
|
||||
confidence += 30;
|
||||
matchedKeywords.push(term);
|
||||
}
|
||||
}
|
||||
|
||||
const descLower = (skill.description || '').toLowerCase();
|
||||
for (const term of queryTerms) {
|
||||
if (descLower.includes(term) && !matchedKeywords.includes(term)) {
|
||||
confidence += 20;
|
||||
matchedKeywords.push(term);
|
||||
}
|
||||
}
|
||||
|
||||
const tagsLower = (skill.tags || []).map((t) => t.toLowerCase());
|
||||
for (const term of queryTerms) {
|
||||
if (tagsLower.some((t) => t.includes(term) || term.includes(t))) {
|
||||
if (!matchedKeywords.includes(term)) {
|
||||
confidence += 25;
|
||||
matchedKeywords.push(term);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (context) {
|
||||
for (const framework of context.stack.frameworks) {
|
||||
const fwLower = framework.name.toLowerCase();
|
||||
if (tagsLower.includes(fwLower) || nameLower.includes(fwLower)) {
|
||||
confidence += 15;
|
||||
}
|
||||
}
|
||||
|
||||
for (const language of context.stack.languages) {
|
||||
const langLower = language.name.toLowerCase();
|
||||
if (tagsLower.includes(langLower) || nameLower.includes(langLower)) {
|
||||
confidence += 10;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
confidence = Math.min(100, confidence);
|
||||
|
||||
const relevantSections: string[] = [];
|
||||
if (matchedKeywords.length > 0) {
|
||||
relevantSections.push('description', 'tags');
|
||||
}
|
||||
|
||||
const reasoning = matchedKeywords.length > 0
|
||||
? `Matches keywords: ${matchedKeywords.join(', ')}`
|
||||
: 'No direct keyword match';
|
||||
|
||||
return {
|
||||
confidence,
|
||||
reasoning,
|
||||
relevantSections,
|
||||
matchedKeywords,
|
||||
};
|
||||
}
|
||||
|
||||
private fallbackSearch(query: TreeSearchQuery): TreeSearchResult[] {
|
||||
const results: TreeSearchResult[] = [];
|
||||
|
||||
for (const skill of this.skillMap.values()) {
|
||||
const matchResult = this.evaluateSkillMatch(
|
||||
query.query,
|
||||
skill,
|
||||
query.context
|
||||
);
|
||||
|
||||
if (matchResult.confidence >= (query.minConfidence ?? 30)) {
|
||||
results.push({
|
||||
skill,
|
||||
path: ['Uncategorized'],
|
||||
reasoning: matchResult.reasoning,
|
||||
confidence: matchResult.confidence,
|
||||
relevantSections: matchResult.relevantSections,
|
||||
matchedKeywords: matchResult.matchedKeywords,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
return results;
|
||||
}
|
||||
|
||||
private async generateExplanation(
|
||||
skill: SkillSummary,
|
||||
score: number,
|
||||
profile: ProjectProfile
|
||||
): Promise<ExplainedMatch> {
|
||||
if (this.config.provider === 'mock') {
|
||||
return this.mockExplanation(skill, score, profile);
|
||||
}
|
||||
|
||||
const prompt = buildExplanationPrompt(skill, score, profile);
|
||||
|
||||
try {
|
||||
const response = await this.callLLM(prompt);
|
||||
const data = extractJsonFromResponse(response) as Partial<ExplainedMatch>;
|
||||
|
||||
return {
|
||||
matchedBecause: data.matchedBecause || [],
|
||||
relevantFor: data.relevantFor || [],
|
||||
differentFrom: data.differentFrom || [],
|
||||
confidence: data.confidence || this.scoreToConfidence(score),
|
||||
};
|
||||
} catch {
|
||||
return this.mockExplanation(skill, score, profile);
|
||||
}
|
||||
}
|
||||
|
||||
private mockExplanation(
|
||||
skill: SkillSummary,
|
||||
score: number,
|
||||
profile: ProjectProfile
|
||||
): ExplainedMatch {
|
||||
const matchedBecause: string[] = [];
|
||||
const relevantFor: string[] = [];
|
||||
const differentFrom: string[] = [];
|
||||
|
||||
const skillTags = skill.tags || [];
|
||||
|
||||
for (const framework of profile.stack.frameworks) {
|
||||
const fwLower = framework.name.toLowerCase();
|
||||
if (
|
||||
skillTags.some((t) => t.toLowerCase().includes(fwLower)) ||
|
||||
skill.name.toLowerCase().includes(fwLower)
|
||||
) {
|
||||
matchedBecause.push(`Uses ${framework.name}`);
|
||||
}
|
||||
}
|
||||
|
||||
for (const language of profile.stack.languages) {
|
||||
const langLower = language.name.toLowerCase();
|
||||
if (skillTags.some((t) => t.toLowerCase().includes(langLower))) {
|
||||
matchedBecause.push(`Supports ${language.name}`);
|
||||
}
|
||||
}
|
||||
|
||||
if (matchedBecause.length === 0) {
|
||||
matchedBecause.push(`Related tags: ${skillTags.slice(0, 3).join(', ')}`);
|
||||
}
|
||||
|
||||
relevantFor.push(`Your ${profile.type || 'project'} project`);
|
||||
if (profile.name) {
|
||||
relevantFor.push(`Specifically for ${profile.name}`);
|
||||
}
|
||||
|
||||
differentFrom.push('General-purpose alternatives');
|
||||
|
||||
return {
|
||||
matchedBecause,
|
||||
relevantFor,
|
||||
differentFrom,
|
||||
confidence: this.scoreToConfidence(score),
|
||||
};
|
||||
}
|
||||
|
||||
private scoreToConfidence(score: number): 'high' | 'medium' | 'low' {
|
||||
if (score >= 70) return 'high';
|
||||
if (score >= 50) return 'medium';
|
||||
return 'low';
|
||||
}
|
||||
|
||||
private getSkillPath(skillName: string): string[] {
|
||||
if (!this.tree) return ['Uncategorized'];
|
||||
|
||||
const generator = new TreeGenerator();
|
||||
const path = generator.getPath(this.tree, skillName);
|
||||
return path || ['Uncategorized'];
|
||||
}
|
||||
|
||||
private buildReasoningSummary(
|
||||
plan: SearchPlan,
|
||||
results: TreeSearchResult[]
|
||||
): string {
|
||||
const parts: string[] = [];
|
||||
|
||||
parts.push(`Search strategy: ${plan.strategy}`);
|
||||
parts.push(`Primary categories: ${plan.primaryCategories.join(', ')}`);
|
||||
|
||||
if (plan.keywords.length > 0) {
|
||||
parts.push(`Keywords extracted: ${plan.keywords.join(', ')}`);
|
||||
}
|
||||
|
||||
parts.push(`Found ${results.length} matching skills`);
|
||||
|
||||
if (results.length > 0) {
|
||||
const avgConfidence = results.reduce((sum, r) => sum + r.confidence, 0) / results.length;
|
||||
parts.push(`Average confidence: ${Math.round(avgConfidence)}%`);
|
||||
}
|
||||
|
||||
return parts.join('. ');
|
||||
}
|
||||
|
||||
private async callLLM(prompt: string): Promise<string> {
|
||||
return `Mock response for: ${prompt.slice(0, 50)}...`;
|
||||
}
|
||||
|
||||
private getCacheKey(query: TreeSearchQuery): string {
|
||||
return JSON.stringify({
|
||||
query: query.query,
|
||||
contextName: query.context?.name,
|
||||
maxResults: query.maxResults,
|
||||
minConfidence: query.minConfidence,
|
||||
});
|
||||
}
|
||||
|
||||
private getFromCache(key: string): ReasoningCacheEntry | null {
|
||||
const entry = this.cache.get(key);
|
||||
if (!entry) return null;
|
||||
|
||||
const now = Date.now();
|
||||
if (now - entry.timestamp > entry.ttl) {
|
||||
this.cache.delete(key);
|
||||
return null;
|
||||
}
|
||||
|
||||
return entry;
|
||||
}
|
||||
|
||||
private addToCache(key: string, results: TreeSearchResult[]): void {
|
||||
if (this.cache.size >= MAX_CACHE_SIZE) {
|
||||
const oldestKey = this.cache.keys().next().value;
|
||||
if (oldestKey) {
|
||||
this.cache.delete(oldestKey);
|
||||
}
|
||||
}
|
||||
|
||||
this.cache.set(key, {
|
||||
query: key,
|
||||
results,
|
||||
timestamp: Date.now(),
|
||||
ttl: CACHE_TTL_MS,
|
||||
});
|
||||
}
|
||||
|
||||
private updateStats(processingTimeMs: number, resultCount: number): void {
|
||||
const cacheMisses = this.stats.cacheMisses;
|
||||
|
||||
if (cacheMisses === 1) {
|
||||
this.stats.averageProcessingTimeMs = processingTimeMs;
|
||||
this.stats.averageResultsPerQuery = resultCount;
|
||||
} else {
|
||||
this.stats.averageProcessingTimeMs =
|
||||
(this.stats.averageProcessingTimeMs * (cacheMisses - 1) + processingTimeMs) / cacheMisses;
|
||||
this.stats.averageResultsPerQuery =
|
||||
(this.stats.averageResultsPerQuery * (cacheMisses - 1) + resultCount) / cacheMisses;
|
||||
}
|
||||
}
|
||||
|
||||
getStats(): ReasoningEngineStats {
|
||||
return { ...this.stats };
|
||||
}
|
||||
|
||||
clearCache(): void {
|
||||
this.cache.clear();
|
||||
}
|
||||
|
||||
getTree(): SkillTree | null {
|
||||
return this.tree;
|
||||
}
|
||||
}
|
||||
|
||||
export function createReasoningEngine(
|
||||
config?: Partial<ReasoningConfig>
|
||||
): ReasoningEngine {
|
||||
return new ReasoningEngine(config);
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
export * from './types.js';
|
||||
export * from './engine.js';
|
||||
export * from './prompts.js';
|
||||
|
||||
export { ReasoningEngine, createReasoningEngine } from './engine.js';
|
||||
export {
|
||||
buildSearchPlanPrompt,
|
||||
buildCategoryRelevancePrompt,
|
||||
buildSkillMatchPrompt,
|
||||
buildExplanationPrompt,
|
||||
extractJsonFromResponse,
|
||||
validateSearchPlan,
|
||||
validateCategoryScore,
|
||||
} from './prompts.js';
|
||||
@@ -0,0 +1,227 @@
|
||||
import type { TreeNode } from '../tree/types.js';
|
||||
import type { ProjectProfile } from '../recommend/types.js';
|
||||
import type { SearchPlan, CategoryScore } from './types.js';
|
||||
|
||||
export const SEARCH_PLANNING_PROMPT = `You are a skill discovery assistant. Given a user query and optional project context, create a search plan.
|
||||
|
||||
User Query: {{query}}
|
||||
|
||||
{{#if context}}
|
||||
Project Context:
|
||||
- Languages: {{context.languages}}
|
||||
- Frameworks: {{context.frameworks}}
|
||||
- Project Type: {{context.type}}
|
||||
{{/if}}
|
||||
|
||||
Available Categories:
|
||||
{{categories}}
|
||||
|
||||
Respond with a JSON search plan:
|
||||
{
|
||||
"primaryCategories": ["most relevant categories"],
|
||||
"secondaryCategories": ["somewhat relevant categories"],
|
||||
"keywords": ["extracted search terms"],
|
||||
"filters": {
|
||||
"tags": ["relevant tags"],
|
||||
"frameworks": ["relevant frameworks"],
|
||||
"languages": ["relevant languages"]
|
||||
},
|
||||
"strategy": "breadth-first" | "depth-first" | "targeted"
|
||||
}`;
|
||||
|
||||
export const CATEGORY_RELEVANCE_PROMPT = `Rate the relevance of this category for the user's query.
|
||||
|
||||
Query: {{query}}
|
||||
|
||||
Category: {{category.name}}
|
||||
Skills in category: {{category.skillCount}}
|
||||
Subcategories: {{category.subcategories}}
|
||||
|
||||
Rate from 0-100 and explain briefly.
|
||||
Respond as JSON: {"score": number, "reasoning": "brief explanation"}`;
|
||||
|
||||
export const SKILL_MATCH_PROMPT = `Evaluate how well this skill matches the user's query.
|
||||
|
||||
Query: {{query}}
|
||||
|
||||
Skill: {{skill.name}}
|
||||
Description: {{skill.description}}
|
||||
Tags: {{skill.tags}}
|
||||
|
||||
{{#if context}}
|
||||
Project Stack:
|
||||
- Languages: {{context.languages}}
|
||||
- Frameworks: {{context.frameworks}}
|
||||
{{/if}}
|
||||
|
||||
Evaluate match quality and explain why.
|
||||
Respond as JSON:
|
||||
{
|
||||
"confidence": 0-100,
|
||||
"matchedKeywords": ["words from query that match"],
|
||||
"relevantSections": ["which parts of skill are relevant"],
|
||||
"reasoning": "explanation of match quality"
|
||||
}`;
|
||||
|
||||
export const EXPLANATION_PROMPT = `Explain why this skill was recommended for the user's project.
|
||||
|
||||
Skill: {{skill.name}}
|
||||
Description: {{skill.description}}
|
||||
Tags: {{skill.tags}}
|
||||
Score: {{score}}
|
||||
|
||||
Project:
|
||||
- Name: {{project.name}}
|
||||
- Type: {{project.type}}
|
||||
- Languages: {{project.languages}}
|
||||
- Frameworks: {{project.frameworks}}
|
||||
|
||||
Explain the match clearly and concisely.
|
||||
Respond as JSON:
|
||||
{
|
||||
"matchedBecause": ["specific match reasons"],
|
||||
"relevantFor": ["how it helps this project"],
|
||||
"differentFrom": ["what distinguishes it from alternatives"],
|
||||
"confidence": "high" | "medium" | "low"
|
||||
}`;
|
||||
|
||||
export function buildSearchPlanPrompt(
|
||||
query: string,
|
||||
categories: string[],
|
||||
context?: ProjectProfile
|
||||
): string {
|
||||
let prompt = SEARCH_PLANNING_PROMPT
|
||||
.replace('{{query}}', query)
|
||||
.replace('{{categories}}', categories.join('\n'));
|
||||
|
||||
if (context) {
|
||||
const languages = context.stack.languages.map(l => l.name).join(', ');
|
||||
const frameworks = context.stack.frameworks.map(f => f.name).join(', ');
|
||||
|
||||
prompt = prompt
|
||||
.replace('{{#if context}}', '')
|
||||
.replace('{{/if}}', '')
|
||||
.replace('{{context.languages}}', languages)
|
||||
.replace('{{context.frameworks}}', frameworks)
|
||||
.replace('{{context.type}}', context.type || 'unknown');
|
||||
} else {
|
||||
prompt = prompt.replace(/\{\{#if context\}\}[\s\S]*?\{\{\/if\}\}/g, '');
|
||||
}
|
||||
|
||||
return prompt;
|
||||
}
|
||||
|
||||
export function buildCategoryRelevancePrompt(
|
||||
query: string,
|
||||
node: TreeNode
|
||||
): string {
|
||||
const subcategories = node.children.map(c => c.name).join(', ');
|
||||
|
||||
return CATEGORY_RELEVANCE_PROMPT
|
||||
.replace('{{query}}', query)
|
||||
.replace('{{category.name}}', node.name)
|
||||
.replace('{{category.skillCount}}', String(node.skillCount))
|
||||
.replace('{{category.subcategories}}', subcategories || 'none');
|
||||
}
|
||||
|
||||
export function buildSkillMatchPrompt(
|
||||
query: string,
|
||||
skill: { name: string; description?: string; tags?: string[] },
|
||||
context?: ProjectProfile
|
||||
): string {
|
||||
let prompt = SKILL_MATCH_PROMPT
|
||||
.replace('{{query}}', query)
|
||||
.replace('{{skill.name}}', skill.name)
|
||||
.replace('{{skill.description}}', skill.description || 'No description')
|
||||
.replace('{{skill.tags}}', skill.tags?.join(', ') || 'No tags');
|
||||
|
||||
if (context) {
|
||||
const languages = context.stack.languages.map(l => l.name).join(', ');
|
||||
const frameworks = context.stack.frameworks.map(f => f.name).join(', ');
|
||||
|
||||
prompt = prompt
|
||||
.replace('{{#if context}}', '')
|
||||
.replace('{{/if}}', '')
|
||||
.replace('{{context.languages}}', languages)
|
||||
.replace('{{context.frameworks}}', frameworks);
|
||||
} else {
|
||||
prompt = prompt.replace(/\{\{#if context\}\}[\s\S]*?\{\{\/if\}\}/g, '');
|
||||
}
|
||||
|
||||
return prompt;
|
||||
}
|
||||
|
||||
export function buildExplanationPrompt(
|
||||
skill: { name: string; description?: string; tags?: string[] },
|
||||
score: number,
|
||||
project: ProjectProfile
|
||||
): string {
|
||||
const languages = project.stack.languages.map(l => l.name).join(', ');
|
||||
const frameworks = project.stack.frameworks.map(f => f.name).join(', ');
|
||||
|
||||
return EXPLANATION_PROMPT
|
||||
.replace('{{skill.name}}', skill.name)
|
||||
.replace('{{skill.description}}', skill.description || 'No description')
|
||||
.replace('{{skill.tags}}', skill.tags?.join(', ') || 'No tags')
|
||||
.replace('{{score}}', String(score))
|
||||
.replace('{{project.name}}', project.name)
|
||||
.replace('{{project.type}}', project.type || 'unknown')
|
||||
.replace('{{project.languages}}', languages)
|
||||
.replace('{{project.frameworks}}', frameworks);
|
||||
}
|
||||
|
||||
export function extractJsonFromResponse(response: string): unknown {
|
||||
const jsonMatch = response.match(/\{[\s\S]*\}/);
|
||||
if (!jsonMatch) {
|
||||
throw new Error('No JSON found in response');
|
||||
}
|
||||
|
||||
try {
|
||||
return JSON.parse(jsonMatch[0]);
|
||||
} catch {
|
||||
throw new Error('Invalid JSON in response');
|
||||
}
|
||||
}
|
||||
|
||||
export function validateSearchPlan(data: unknown): SearchPlan {
|
||||
const plan = data as Record<string, unknown>;
|
||||
|
||||
return {
|
||||
primaryCategories: Array.isArray(plan.primaryCategories)
|
||||
? plan.primaryCategories
|
||||
: [],
|
||||
secondaryCategories: Array.isArray(plan.secondaryCategories)
|
||||
? plan.secondaryCategories
|
||||
: [],
|
||||
keywords: Array.isArray(plan.keywords) ? plan.keywords : [],
|
||||
filters: {
|
||||
tags: Array.isArray((plan.filters as Record<string, unknown>)?.tags)
|
||||
? (plan.filters as Record<string, unknown>).tags as string[]
|
||||
: [],
|
||||
frameworks: Array.isArray((plan.filters as Record<string, unknown>)?.frameworks)
|
||||
? (plan.filters as Record<string, unknown>).frameworks as string[]
|
||||
: [],
|
||||
languages: Array.isArray((plan.filters as Record<string, unknown>)?.languages)
|
||||
? (plan.filters as Record<string, unknown>).languages as string[]
|
||||
: [],
|
||||
},
|
||||
strategy: ['breadth-first', 'depth-first', 'targeted'].includes(
|
||||
plan.strategy as string
|
||||
)
|
||||
? (plan.strategy as 'breadth-first' | 'depth-first' | 'targeted')
|
||||
: 'breadth-first',
|
||||
};
|
||||
}
|
||||
|
||||
export function validateCategoryScore(
|
||||
data: unknown,
|
||||
fallbackCategory = ''
|
||||
): CategoryScore {
|
||||
const score = data as Record<string, unknown>;
|
||||
|
||||
return {
|
||||
category: typeof score.category === 'string' ? score.category : fallbackCategory,
|
||||
score: typeof score.score === 'number' ? Math.min(100, Math.max(0, score.score)) : 0,
|
||||
reasoning: typeof score.reasoning === 'string' ? score.reasoning : '',
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,115 @@
|
||||
import { z } from 'zod';
|
||||
import type { SkillSummary, ProjectProfile } from '../recommend/types.js';
|
||||
import type { TreeNode } from '../tree/types.js';
|
||||
|
||||
export const ReasoningProviderSchema = z.enum(['openai', 'anthropic', 'ollama', 'mock']);
|
||||
export type ReasoningProvider = z.infer<typeof ReasoningProviderSchema>;
|
||||
|
||||
export interface ReasoningConfig {
|
||||
provider: ReasoningProvider;
|
||||
apiKey?: string;
|
||||
model?: string;
|
||||
maxTokens?: number;
|
||||
temperature?: number;
|
||||
baseUrl?: string;
|
||||
}
|
||||
|
||||
export interface TreeSearchQuery {
|
||||
query: string;
|
||||
context?: ProjectProfile;
|
||||
maxResults?: number;
|
||||
minConfidence?: number;
|
||||
searchDepth?: number;
|
||||
}
|
||||
|
||||
export interface TreeTraversalStep {
|
||||
node: TreeNode;
|
||||
reasoning: string;
|
||||
confidence: number;
|
||||
action: 'explore' | 'skip' | 'select';
|
||||
selectedSkills: string[];
|
||||
}
|
||||
|
||||
export interface TreeSearchResult {
|
||||
skill: SkillSummary;
|
||||
path: string[];
|
||||
reasoning: string;
|
||||
confidence: number;
|
||||
relevantSections: string[];
|
||||
matchedKeywords: string[];
|
||||
}
|
||||
|
||||
export interface TreeReasoningResult {
|
||||
query: string;
|
||||
results: TreeSearchResult[];
|
||||
exploredPaths: string[][];
|
||||
reasoning: string;
|
||||
totalNodesVisited: number;
|
||||
processingTimeMs: number;
|
||||
}
|
||||
|
||||
export interface ExplainedMatch {
|
||||
matchedBecause: string[];
|
||||
relevantFor: string[];
|
||||
differentFrom: string[];
|
||||
confidence: 'high' | 'medium' | 'low';
|
||||
}
|
||||
|
||||
export interface ExplainedRecommendation {
|
||||
skill: SkillSummary;
|
||||
score: number;
|
||||
reasoning: ExplainedMatch;
|
||||
treePath: string[];
|
||||
}
|
||||
|
||||
export interface ReasoningPrompt {
|
||||
name: string;
|
||||
template: string;
|
||||
variables: string[];
|
||||
}
|
||||
|
||||
export interface LLMResponse {
|
||||
content: string;
|
||||
tokensUsed: number;
|
||||
model: string;
|
||||
}
|
||||
|
||||
export interface ReasoningCacheEntry {
|
||||
query: string;
|
||||
results: TreeSearchResult[];
|
||||
timestamp: number;
|
||||
ttl: number;
|
||||
}
|
||||
|
||||
export const DEFAULT_REASONING_CONFIG: ReasoningConfig = {
|
||||
provider: 'mock',
|
||||
model: 'gpt-4o-mini',
|
||||
maxTokens: 1000,
|
||||
temperature: 0.3,
|
||||
};
|
||||
|
||||
export interface CategoryScore {
|
||||
category: string;
|
||||
score: number;
|
||||
reasoning: string;
|
||||
}
|
||||
|
||||
export interface SearchPlan {
|
||||
primaryCategories: string[];
|
||||
secondaryCategories: string[];
|
||||
keywords: string[];
|
||||
filters: {
|
||||
tags?: string[];
|
||||
frameworks?: string[];
|
||||
languages?: string[];
|
||||
};
|
||||
strategy: 'breadth-first' | 'depth-first' | 'targeted';
|
||||
}
|
||||
|
||||
export interface ReasoningEngineStats {
|
||||
totalQueries: number;
|
||||
cacheHits: number;
|
||||
cacheMisses: number;
|
||||
averageProcessingTimeMs: number;
|
||||
averageResultsPerQuery: number;
|
||||
}
|
||||
@@ -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
|
||||
*
|
||||
@@ -665,3 +756,145 @@ export function createRecommendationEngine(
|
||||
): RecommendationEngine {
|
||||
return new RecommendationEngine(weights);
|
||||
}
|
||||
|
||||
/**
|
||||
* Enhanced Recommendation Engine with reasoning support
|
||||
*/
|
||||
export class ReasoningRecommendationEngine extends RecommendationEngine {
|
||||
private reasoningEngine: import('../reasoning/engine.js').ReasoningEngine | null = null;
|
||||
private reasoningConfig?: import('../reasoning/types.js').ReasoningConfig;
|
||||
|
||||
constructor(
|
||||
weights?: Partial<ScoringWeights>,
|
||||
reasoningConfig?: Partial<import('../reasoning/types.js').ReasoningConfig>
|
||||
) {
|
||||
super(weights);
|
||||
this.reasoningConfig = reasoningConfig as import('../reasoning/types.js').ReasoningConfig;
|
||||
}
|
||||
|
||||
async initReasoning(): Promise<void> {
|
||||
const { createReasoningEngine } = await import('../reasoning/engine.js');
|
||||
this.reasoningEngine = createReasoningEngine(this.reasoningConfig);
|
||||
|
||||
const index = this.getIndex();
|
||||
if (index) {
|
||||
this.reasoningEngine.loadSkills(index.skills);
|
||||
this.reasoningEngine.generateTree(index.skills);
|
||||
}
|
||||
}
|
||||
|
||||
async recommendWithReasoning(
|
||||
profile: ProjectProfile,
|
||||
options: import('./types.js').ReasoningRecommendOptions = {}
|
||||
): Promise<import('./types.js').ReasoningRecommendationResult> {
|
||||
const baseResult = this.recommend(profile, options);
|
||||
|
||||
if (!options.reasoning || !this.reasoningEngine) {
|
||||
return {
|
||||
...baseResult,
|
||||
recommendations: baseResult.recommendations.map((r) => ({
|
||||
...r,
|
||||
treePath: [],
|
||||
})),
|
||||
};
|
||||
}
|
||||
|
||||
const searchResult = await this.reasoningEngine.search({
|
||||
query: this.buildQueryFromProfile(profile),
|
||||
context: profile,
|
||||
maxResults: options.limit ?? 10,
|
||||
minConfidence: options.minScore ?? 30,
|
||||
});
|
||||
|
||||
const enhancedRecommendations: import('./types.js').ExplainedScoredSkill[] = [];
|
||||
|
||||
for (const rec of baseResult.recommendations) {
|
||||
const treeResult = searchResult.results.find(
|
||||
(r) => r.skill.name === rec.skill.name
|
||||
);
|
||||
|
||||
let explanation: import('./types.js').ExplainedMatchDetails | undefined;
|
||||
|
||||
if (options.explainResults) {
|
||||
const explainedRec = await this.reasoningEngine.explain(
|
||||
rec.skill,
|
||||
rec.score,
|
||||
profile
|
||||
);
|
||||
explanation = explainedRec.reasoning;
|
||||
}
|
||||
|
||||
enhancedRecommendations.push({
|
||||
...rec,
|
||||
explanation,
|
||||
treePath: treeResult?.path ?? [],
|
||||
reasoningDetails: treeResult?.reasoning,
|
||||
});
|
||||
}
|
||||
|
||||
return {
|
||||
...baseResult,
|
||||
recommendations: enhancedRecommendations,
|
||||
reasoningSummary: searchResult.reasoning,
|
||||
searchPlan: {
|
||||
primaryCategories: [],
|
||||
secondaryCategories: [],
|
||||
keywords: this.extractKeywords(profile),
|
||||
strategy: 'breadth-first',
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
private buildQueryFromProfile(profile: ProjectProfile): string {
|
||||
const parts: string[] = [];
|
||||
|
||||
if (profile.type) {
|
||||
parts.push(profile.type);
|
||||
}
|
||||
|
||||
for (const framework of profile.stack.frameworks.slice(0, 3)) {
|
||||
parts.push(framework.name);
|
||||
}
|
||||
|
||||
for (const language of profile.stack.languages.slice(0, 2)) {
|
||||
parts.push(language.name);
|
||||
}
|
||||
|
||||
return parts.join(' ');
|
||||
}
|
||||
|
||||
private extractKeywords(profile: ProjectProfile): string[] {
|
||||
const keywords: string[] = [];
|
||||
|
||||
if (profile.type) {
|
||||
keywords.push(profile.type);
|
||||
}
|
||||
|
||||
for (const framework of profile.stack.frameworks) {
|
||||
keywords.push(framework.name.toLowerCase());
|
||||
}
|
||||
|
||||
for (const language of profile.stack.languages) {
|
||||
keywords.push(language.name.toLowerCase());
|
||||
}
|
||||
|
||||
return [...new Set(keywords)];
|
||||
}
|
||||
|
||||
getReasoningStats(): import('../reasoning/types.js').ReasoningEngineStats | null {
|
||||
return this.reasoningEngine?.getStats() ?? null;
|
||||
}
|
||||
|
||||
getSkillTree(): import('../tree/types.js').SkillTree | null {
|
||||
return this.reasoningEngine?.getTree() ?? null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create an enhanced recommendation engine with reasoning support
|
||||
*/
|
||||
export function createReasoningRecommendationEngine(
|
||||
weights?: Partial<ScoringWeights>
|
||||
): ReasoningRecommendationEngine {
|
||||
return new ReasoningRecommendationEngine(weights);
|
||||
}
|
||||
|
||||
@@ -14,7 +14,12 @@
|
||||
export * from './types.js';
|
||||
export * from './engine.js';
|
||||
export * from './fetcher.js';
|
||||
export { createRecommendationEngine, RecommendationEngine } from './engine.js';
|
||||
export {
|
||||
createRecommendationEngine,
|
||||
RecommendationEngine,
|
||||
ReasoningRecommendationEngine,
|
||||
createReasoningRecommendationEngine,
|
||||
} from './engine.js';
|
||||
export {
|
||||
fetchSkillsFromRepo,
|
||||
buildSkillIndex,
|
||||
|
||||
@@ -284,3 +284,67 @@ export function getTechTags(techName: string): string[] {
|
||||
}
|
||||
return tags;
|
||||
}
|
||||
|
||||
/**
|
||||
* Enhanced recommendation options with reasoning support
|
||||
*/
|
||||
export interface ReasoningRecommendOptions extends RecommendOptions {
|
||||
reasoning?: boolean;
|
||||
explainResults?: boolean;
|
||||
useTree?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Explained match details
|
||||
*/
|
||||
export interface ExplainedMatchDetails {
|
||||
matchedBecause: string[];
|
||||
relevantFor: string[];
|
||||
differentFrom: string[];
|
||||
confidence: 'high' | 'medium' | 'low';
|
||||
}
|
||||
|
||||
/**
|
||||
* Enhanced scored skill with reasoning
|
||||
*/
|
||||
export interface ExplainedScoredSkill extends ScoredSkill {
|
||||
explanation?: ExplainedMatchDetails;
|
||||
treePath?: string[];
|
||||
reasoningDetails?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Enhanced recommendation result with reasoning
|
||||
*/
|
||||
export interface ReasoningRecommendationResult extends RecommendationResult {
|
||||
recommendations: ExplainedScoredSkill[];
|
||||
reasoningSummary?: string;
|
||||
searchPlan?: {
|
||||
primaryCategories: string[];
|
||||
secondaryCategories: string[];
|
||||
keywords: string[];
|
||||
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[];
|
||||
}
|
||||
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -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);
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
@@ -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();
|
||||
}
|
||||
}
|
||||
@@ -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';
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
@@ -0,0 +1,352 @@
|
||||
import type { SkillSummary } from '../recommend/types.js';
|
||||
import {
|
||||
type TreeNode,
|
||||
type SkillTree,
|
||||
type TreeGeneratorOptions,
|
||||
type CategoryMapping,
|
||||
CATEGORY_TAXONOMY,
|
||||
} from './types.js';
|
||||
|
||||
const DEFAULT_OPTIONS: Required<TreeGeneratorOptions> = {
|
||||
maxDepth: 3,
|
||||
minSkillsPerNode: 1,
|
||||
includeEmpty: false,
|
||||
};
|
||||
|
||||
export class TreeGenerator {
|
||||
private options: Required<TreeGeneratorOptions>;
|
||||
|
||||
constructor(options?: TreeGeneratorOptions) {
|
||||
this.options = { ...DEFAULT_OPTIONS, ...options };
|
||||
}
|
||||
|
||||
generateTree(skills: SkillSummary[]): SkillTree {
|
||||
const rootNode = this.buildTreeFromTaxonomy(skills);
|
||||
const { totalCategories, maxDepth } = this.countTreeStats(rootNode);
|
||||
|
||||
return {
|
||||
version: 1,
|
||||
generatedAt: new Date().toISOString(),
|
||||
rootNode,
|
||||
totalSkills: skills.length,
|
||||
totalCategories,
|
||||
maxDepth,
|
||||
};
|
||||
}
|
||||
|
||||
private buildTreeFromTaxonomy(skills: SkillSummary[]): TreeNode {
|
||||
const root: TreeNode = {
|
||||
id: 'root',
|
||||
name: 'Skills',
|
||||
description: 'All available skills organized by category',
|
||||
children: [],
|
||||
skills: [],
|
||||
skillCount: skills.length,
|
||||
depth: 0,
|
||||
};
|
||||
|
||||
const uncategorized: string[] = [];
|
||||
|
||||
for (const category of CATEGORY_TAXONOMY) {
|
||||
const categoryNode = this.buildCategoryNode(category, skills, 1);
|
||||
if (categoryNode.skillCount > 0 || this.options.includeEmpty) {
|
||||
root.children.push(categoryNode);
|
||||
}
|
||||
}
|
||||
|
||||
for (const skill of skills) {
|
||||
if (!this.isSkillCategorized(skill)) {
|
||||
uncategorized.push(skill.name);
|
||||
}
|
||||
}
|
||||
|
||||
if (uncategorized.length > 0) {
|
||||
root.children.push({
|
||||
id: 'other',
|
||||
name: 'Other',
|
||||
description: 'Skills without specific categorization',
|
||||
children: [],
|
||||
skills: uncategorized,
|
||||
skillCount: uncategorized.length,
|
||||
depth: 1,
|
||||
});
|
||||
}
|
||||
|
||||
return root;
|
||||
}
|
||||
|
||||
private buildCategoryNode(
|
||||
category: CategoryMapping,
|
||||
skills: SkillSummary[],
|
||||
depth: number
|
||||
): TreeNode {
|
||||
const categorySkills = this.filterSkillsByCategory(skills, category);
|
||||
const subcategoryNodes: TreeNode[] = [];
|
||||
|
||||
if (depth < this.options.maxDepth) {
|
||||
for (const subcategory of category.subcategories) {
|
||||
const subcategorySkills = this.filterSkillsBySubcategory(
|
||||
categorySkills,
|
||||
subcategory,
|
||||
category
|
||||
);
|
||||
|
||||
if (
|
||||
subcategorySkills.length >= this.options.minSkillsPerNode ||
|
||||
this.options.includeEmpty
|
||||
) {
|
||||
subcategoryNodes.push({
|
||||
id: `${category.category.toLowerCase().replace(/[^a-z0-9]/g, '-')}-${subcategory.toLowerCase().replace(/[^a-z0-9]/g, '-')}`,
|
||||
name: subcategory,
|
||||
description: `${subcategory} skills in ${category.category}`,
|
||||
children: [],
|
||||
skills: subcategorySkills.map((s) => s.name),
|
||||
skillCount: subcategorySkills.length,
|
||||
depth: depth + 1,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const directSkills = categorySkills.filter(
|
||||
(skill) =>
|
||||
!subcategoryNodes.some((node) => node.skills.includes(skill.name))
|
||||
);
|
||||
|
||||
const totalSkillCount =
|
||||
directSkills.length +
|
||||
subcategoryNodes.reduce((sum, node) => sum + node.skillCount, 0);
|
||||
|
||||
return {
|
||||
id: category.category.toLowerCase().replace(/[^a-z0-9]/g, '-'),
|
||||
name: category.category,
|
||||
description: `${category.category} related skills`,
|
||||
children: subcategoryNodes,
|
||||
skills: directSkills.map((s) => s.name),
|
||||
skillCount: totalSkillCount,
|
||||
depth,
|
||||
};
|
||||
}
|
||||
|
||||
private filterSkillsByCategory(
|
||||
skills: SkillSummary[],
|
||||
category: CategoryMapping
|
||||
): SkillSummary[] {
|
||||
return skills.filter((skill) => {
|
||||
const skillTags = (skill.tags || []).map((t) => t.toLowerCase());
|
||||
const skillName = skill.name.toLowerCase();
|
||||
const skillDesc = (skill.description || '').toLowerCase();
|
||||
|
||||
const tagMatch = skillTags.some((tag) =>
|
||||
category.tags.includes(tag)
|
||||
);
|
||||
|
||||
const keywordMatch = category.keywords.some(
|
||||
(keyword) =>
|
||||
skillName.includes(keyword) || skillDesc.includes(keyword)
|
||||
);
|
||||
|
||||
const categoryNameMatch =
|
||||
skillName.includes(category.category.toLowerCase()) ||
|
||||
skillDesc.includes(category.category.toLowerCase());
|
||||
|
||||
return tagMatch || keywordMatch || categoryNameMatch;
|
||||
});
|
||||
}
|
||||
|
||||
private filterSkillsBySubcategory(
|
||||
skills: SkillSummary[],
|
||||
subcategory: string,
|
||||
_parentCategory: CategoryMapping
|
||||
): SkillSummary[] {
|
||||
const subcategoryLower = subcategory.toLowerCase();
|
||||
const subcategoryNormalized = subcategoryLower.replace(/[^a-z0-9]/g, '');
|
||||
|
||||
return skills.filter((skill) => {
|
||||
const skillTags = (skill.tags || []).map((t) => t.toLowerCase());
|
||||
const skillName = skill.name.toLowerCase();
|
||||
const skillDesc = (skill.description || '').toLowerCase();
|
||||
|
||||
const tagMatch = skillTags.some(
|
||||
(tag) =>
|
||||
tag === subcategoryLower ||
|
||||
tag === subcategoryNormalized ||
|
||||
tag.includes(subcategoryLower)
|
||||
);
|
||||
|
||||
const nameMatch =
|
||||
skillName.includes(subcategoryLower) ||
|
||||
skillName.includes(subcategoryNormalized);
|
||||
|
||||
const descMatch =
|
||||
skillDesc.includes(subcategoryLower) ||
|
||||
skillDesc.includes(subcategoryNormalized);
|
||||
|
||||
const compatibilityMatch =
|
||||
skill.compatibility?.frameworks?.some(
|
||||
(f) =>
|
||||
f.toLowerCase() === subcategoryLower ||
|
||||
f.toLowerCase() === subcategoryNormalized
|
||||
) ||
|
||||
skill.compatibility?.languages?.some(
|
||||
(l) =>
|
||||
l.toLowerCase() === subcategoryLower ||
|
||||
l.toLowerCase() === subcategoryNormalized
|
||||
);
|
||||
|
||||
return tagMatch || nameMatch || descMatch || compatibilityMatch;
|
||||
});
|
||||
}
|
||||
|
||||
private isSkillCategorized(skill: SkillSummary): boolean {
|
||||
for (const category of CATEGORY_TAXONOMY) {
|
||||
const skillTags = (skill.tags || []).map((t) => t.toLowerCase());
|
||||
const skillName = skill.name.toLowerCase();
|
||||
const skillDesc = (skill.description || '').toLowerCase();
|
||||
|
||||
const tagMatch = skillTags.some((tag) => category.tags.includes(tag));
|
||||
|
||||
const keywordMatch = category.keywords.some(
|
||||
(keyword) =>
|
||||
skillName.includes(keyword) || skillDesc.includes(keyword)
|
||||
);
|
||||
|
||||
if (tagMatch || keywordMatch) {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
private countTreeStats(node: TreeNode): {
|
||||
totalCategories: number;
|
||||
maxDepth: number;
|
||||
} {
|
||||
let totalCategories = 1;
|
||||
let maxDepth = node.depth;
|
||||
|
||||
for (const child of node.children) {
|
||||
const childStats = this.countTreeStats(child);
|
||||
totalCategories += childStats.totalCategories;
|
||||
maxDepth = Math.max(maxDepth, childStats.maxDepth);
|
||||
}
|
||||
|
||||
return { totalCategories, maxDepth };
|
||||
}
|
||||
|
||||
findNode(tree: SkillTree, path: string[]): TreeNode | null {
|
||||
let current = tree.rootNode;
|
||||
|
||||
for (const segment of path) {
|
||||
const child = current.children.find(
|
||||
(c) => c.name.toLowerCase() === segment.toLowerCase()
|
||||
);
|
||||
if (!child) {
|
||||
return null;
|
||||
}
|
||||
current = child;
|
||||
}
|
||||
|
||||
return current;
|
||||
}
|
||||
|
||||
getPath(tree: SkillTree, skillName: string): string[] | null {
|
||||
const findPath = (node: TreeNode, path: string[]): string[] | null => {
|
||||
if (node.skills.includes(skillName)) {
|
||||
return [...path, node.name];
|
||||
}
|
||||
|
||||
for (const child of node.children) {
|
||||
const result = findPath(child, [...path, node.name]);
|
||||
if (result) {
|
||||
return result;
|
||||
}
|
||||
}
|
||||
|
||||
return null;
|
||||
};
|
||||
|
||||
const result = findPath(tree.rootNode, []);
|
||||
return result ? result.slice(1) : null;
|
||||
}
|
||||
|
||||
getAllPaths(tree: SkillTree): Map<string, string[]> {
|
||||
const paths = new Map<string, string[]>();
|
||||
|
||||
const traverse = (node: TreeNode, currentPath: string[]) => {
|
||||
for (const skillName of node.skills) {
|
||||
paths.set(skillName, currentPath);
|
||||
}
|
||||
|
||||
for (const child of node.children) {
|
||||
traverse(child, [...currentPath, child.name]);
|
||||
}
|
||||
};
|
||||
|
||||
traverse(tree.rootNode, []);
|
||||
return paths;
|
||||
}
|
||||
|
||||
getNodesAtDepth(tree: SkillTree, depth: number): TreeNode[] {
|
||||
const nodes: TreeNode[] = [];
|
||||
|
||||
const traverse = (node: TreeNode) => {
|
||||
if (node.depth === depth) {
|
||||
nodes.push(node);
|
||||
} else if (node.depth < depth) {
|
||||
for (const child of node.children) {
|
||||
traverse(child);
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
traverse(tree.rootNode);
|
||||
return nodes;
|
||||
}
|
||||
|
||||
flattenTree(tree: SkillTree): TreeNode[] {
|
||||
const nodes: TreeNode[] = [];
|
||||
|
||||
const traverse = (node: TreeNode) => {
|
||||
nodes.push(node);
|
||||
for (const child of node.children) {
|
||||
traverse(child);
|
||||
}
|
||||
};
|
||||
|
||||
traverse(tree.rootNode);
|
||||
return nodes;
|
||||
}
|
||||
|
||||
searchTree(tree: SkillTree, query: string): TreeNode[] {
|
||||
const queryLower = query.toLowerCase();
|
||||
const results: TreeNode[] = [];
|
||||
|
||||
const traverse = (node: TreeNode) => {
|
||||
const nameMatch = node.name.toLowerCase().includes(queryLower);
|
||||
const descMatch = (node.description || '').toLowerCase().includes(queryLower);
|
||||
const skillMatch = node.skills.some((s) =>
|
||||
s.toLowerCase().includes(queryLower)
|
||||
);
|
||||
|
||||
if (nameMatch || descMatch || skillMatch) {
|
||||
results.push(node);
|
||||
}
|
||||
|
||||
for (const child of node.children) {
|
||||
traverse(child);
|
||||
}
|
||||
};
|
||||
|
||||
traverse(tree.rootNode);
|
||||
return results;
|
||||
}
|
||||
}
|
||||
|
||||
export function generateSkillTree(
|
||||
skills: SkillSummary[],
|
||||
options?: TreeGeneratorOptions
|
||||
): SkillTree {
|
||||
const generator = new TreeGenerator(options);
|
||||
return generator.generateTree(skills);
|
||||
}
|
||||
@@ -0,0 +1,322 @@
|
||||
import type { SkillSummary } from '../recommend/types.js';
|
||||
import type { TreeNode, SkillTree } from './types.js';
|
||||
|
||||
export type RelationType = 'similar' | 'complementary' | 'dependency' | 'alternative';
|
||||
|
||||
export interface SkillRelation {
|
||||
skillName: string;
|
||||
relationType: RelationType;
|
||||
strength: number;
|
||||
reason: string;
|
||||
}
|
||||
|
||||
export interface SkillNode {
|
||||
name: string;
|
||||
tags: string[];
|
||||
source?: string;
|
||||
relations: SkillRelation[];
|
||||
}
|
||||
|
||||
export interface SkillGraph {
|
||||
version: number;
|
||||
generatedAt: string;
|
||||
nodes: Map<string, SkillNode>;
|
||||
totalSkills: number;
|
||||
totalRelations: number;
|
||||
}
|
||||
|
||||
export interface RelatedSkillResult {
|
||||
skill: SkillSummary;
|
||||
relationType: RelationType;
|
||||
strength: number;
|
||||
reason: string;
|
||||
path?: string[];
|
||||
}
|
||||
|
||||
const TAG_SIMILARITY_THRESHOLD = 0.3;
|
||||
const MAX_RELATIONS_PER_SKILL = 10;
|
||||
|
||||
export function buildSkillGraph(skills: SkillSummary[]): SkillGraph {
|
||||
const nodes = new Map<string, SkillNode>();
|
||||
let totalRelations = 0;
|
||||
|
||||
for (const skill of skills) {
|
||||
const node: SkillNode = {
|
||||
name: skill.name,
|
||||
tags: skill.tags || [],
|
||||
source: skill.source,
|
||||
relations: [],
|
||||
};
|
||||
nodes.set(skill.name, node);
|
||||
}
|
||||
|
||||
for (const skill of skills) {
|
||||
const node = nodes.get(skill.name);
|
||||
if (!node) continue;
|
||||
|
||||
const relatedSkills = findRelatedSkills(skill, skills);
|
||||
node.relations = relatedSkills.slice(0, MAX_RELATIONS_PER_SKILL);
|
||||
totalRelations += node.relations.length;
|
||||
}
|
||||
|
||||
return {
|
||||
version: 1,
|
||||
generatedAt: new Date().toISOString(),
|
||||
nodes,
|
||||
totalSkills: skills.length,
|
||||
totalRelations,
|
||||
};
|
||||
}
|
||||
|
||||
function findRelatedSkills(
|
||||
skill: SkillSummary,
|
||||
allSkills: SkillSummary[]
|
||||
): SkillRelation[] {
|
||||
const relations: SkillRelation[] = [];
|
||||
const skillTags = new Set<string>(skill.tags || []);
|
||||
const skillName = skill.name.toLowerCase();
|
||||
|
||||
for (const other of allSkills) {
|
||||
if (other.name === skill.name) continue;
|
||||
|
||||
const otherTags = new Set<string>(other.tags || []);
|
||||
const otherName = other.name.toLowerCase();
|
||||
|
||||
const commonTags: string[] = [...skillTags].filter((tag) => otherTags.has(tag));
|
||||
const totalTags = new Set([...skillTags, ...otherTags]).size;
|
||||
const tagSimilarity = totalTags > 0 ? commonTags.length / totalTags : 0;
|
||||
|
||||
if (tagSimilarity >= TAG_SIMILARITY_THRESHOLD) {
|
||||
const relationType = determineRelationType(skill, other, commonTags);
|
||||
const reason = generateRelationReason(relationType, commonTags);
|
||||
|
||||
relations.push({
|
||||
skillName: other.name,
|
||||
relationType,
|
||||
strength: Math.round(tagSimilarity * 100),
|
||||
reason,
|
||||
});
|
||||
}
|
||||
|
||||
if (skillName.includes(otherName) || otherName.includes(skillName)) {
|
||||
const existing = relations.find((r) => r.skillName === other.name);
|
||||
if (!existing) {
|
||||
relations.push({
|
||||
skillName: other.name,
|
||||
relationType: 'similar',
|
||||
strength: 50,
|
||||
reason: 'Related by name',
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
if (skill.source && other.source && skill.source === other.source) {
|
||||
const existing = relations.find((r) => r.skillName === other.name);
|
||||
if (existing) {
|
||||
existing.strength = Math.min(100, existing.strength + 20);
|
||||
} else if (commonTags.length > 0) {
|
||||
relations.push({
|
||||
skillName: other.name,
|
||||
relationType: 'similar',
|
||||
strength: 30,
|
||||
reason: `Same source: ${skill.source}`,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return relations.sort((a, b) => b.strength - a.strength);
|
||||
}
|
||||
|
||||
function determineRelationType(
|
||||
skill: SkillSummary,
|
||||
other: SkillSummary,
|
||||
_commonTags: string[]
|
||||
): RelationType {
|
||||
const complementaryPairs = [
|
||||
['frontend', 'backend'],
|
||||
['testing', 'development'],
|
||||
['security', 'api'],
|
||||
['database', 'api'],
|
||||
['docker', 'kubernetes'],
|
||||
];
|
||||
|
||||
const skillTags = skill.tags || [];
|
||||
const otherTags = other.tags || [];
|
||||
|
||||
for (const [tag1, tag2] of complementaryPairs) {
|
||||
if (
|
||||
(skillTags.includes(tag1) && otherTags.includes(tag2)) ||
|
||||
(skillTags.includes(tag2) && otherTags.includes(tag1))
|
||||
) {
|
||||
return 'complementary';
|
||||
}
|
||||
}
|
||||
|
||||
const alternativeIndicators = ['vs', 'alternative', 'instead'];
|
||||
const skillName = skill.name.toLowerCase();
|
||||
const otherName = other.name.toLowerCase();
|
||||
|
||||
for (const indicator of alternativeIndicators) {
|
||||
if (skillName.includes(indicator) || otherName.includes(indicator)) {
|
||||
return 'alternative';
|
||||
}
|
||||
}
|
||||
|
||||
return 'similar';
|
||||
}
|
||||
|
||||
function generateRelationReason(relationType: RelationType, commonTags: string[]): string {
|
||||
switch (relationType) {
|
||||
case 'similar':
|
||||
return commonTags.length > 0
|
||||
? `Shares tags: ${commonTags.slice(0, 3).join(', ')}`
|
||||
: 'Similar functionality';
|
||||
case 'complementary':
|
||||
return 'Works well together';
|
||||
case 'dependency':
|
||||
return 'Required by this skill';
|
||||
case 'alternative':
|
||||
return 'Alternative approach';
|
||||
default:
|
||||
return 'Related skill';
|
||||
}
|
||||
}
|
||||
|
||||
export function getRelatedSkills(
|
||||
skillName: string,
|
||||
graph: SkillGraph,
|
||||
skills: SkillSummary[],
|
||||
options: {
|
||||
limit?: number;
|
||||
types?: RelationType[];
|
||||
minStrength?: number;
|
||||
} = {}
|
||||
): RelatedSkillResult[] {
|
||||
const { limit = 5, types, minStrength = 0 } = options;
|
||||
const node = graph.nodes.get(skillName);
|
||||
if (!node) return [];
|
||||
|
||||
const skillMap = new Map(skills.map((s) => [s.name, s]));
|
||||
|
||||
return node.relations
|
||||
.filter((r) => {
|
||||
if (types && !types.includes(r.relationType)) return false;
|
||||
if (r.strength < minStrength) return false;
|
||||
return true;
|
||||
})
|
||||
.slice(0, limit)
|
||||
.map((r) => ({
|
||||
skill: skillMap.get(r.skillName)!,
|
||||
relationType: r.relationType,
|
||||
strength: r.strength,
|
||||
reason: r.reason,
|
||||
}))
|
||||
.filter((r) => r.skill);
|
||||
}
|
||||
|
||||
export function findSkillsByRelationType(
|
||||
graph: SkillGraph,
|
||||
skills: SkillSummary[],
|
||||
relationType: RelationType,
|
||||
limit: number = 10
|
||||
): Array<{ skill: SkillSummary; relatedCount: number }> {
|
||||
const skillMap = new Map(skills.map((s) => [s.name, s]));
|
||||
const counts: Map<string, number> = new Map();
|
||||
|
||||
for (const [_skillName, node] of graph.nodes) {
|
||||
const typeRelations = node.relations.filter((r) => r.relationType === relationType);
|
||||
counts.set(node.name, typeRelations.length);
|
||||
}
|
||||
|
||||
return [...counts.entries()]
|
||||
.sort((a, b) => b[1] - a[1])
|
||||
.slice(0, limit)
|
||||
.map(([name, count]) => ({
|
||||
skill: skillMap.get(name)!,
|
||||
relatedCount: count,
|
||||
}))
|
||||
.filter((r) => r.skill);
|
||||
}
|
||||
|
||||
export function getSkillPath(
|
||||
fromSkillName: string,
|
||||
toSkillName: string,
|
||||
graph: SkillGraph,
|
||||
maxHops: number = 3
|
||||
): string[] | null {
|
||||
if (fromSkillName === toSkillName) return [fromSkillName];
|
||||
|
||||
const visited = new Set<string>();
|
||||
const queue: Array<{ name: string; path: string[] }> = [
|
||||
{ name: fromSkillName, path: [fromSkillName] },
|
||||
];
|
||||
|
||||
while (queue.length > 0) {
|
||||
const current = queue.shift()!;
|
||||
if (current.path.length > maxHops + 1) continue;
|
||||
|
||||
const node = graph.nodes.get(current.name);
|
||||
if (!node) continue;
|
||||
|
||||
for (const relation of node.relations) {
|
||||
if (relation.skillName === toSkillName) {
|
||||
return [...current.path, toSkillName];
|
||||
}
|
||||
|
||||
if (!visited.has(relation.skillName)) {
|
||||
visited.add(relation.skillName);
|
||||
queue.push({
|
||||
name: relation.skillName,
|
||||
path: [...current.path, relation.skillName],
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
export function findSkillsInCategory(tree: SkillTree, categoryPath: string[]): string[] {
|
||||
let current: TreeNode = tree.rootNode;
|
||||
|
||||
for (const segment of categoryPath) {
|
||||
const child = current.children.find(
|
||||
(c) => c.name.toLowerCase() === segment.toLowerCase()
|
||||
);
|
||||
if (!child) return [];
|
||||
current = child;
|
||||
}
|
||||
|
||||
return collectSkillsRecursive(current);
|
||||
}
|
||||
|
||||
function collectSkillsRecursive(node: TreeNode): string[] {
|
||||
const skills: string[] = [...node.skills];
|
||||
for (const child of node.children) {
|
||||
skills.push(...collectSkillsRecursive(child));
|
||||
}
|
||||
return skills;
|
||||
}
|
||||
|
||||
export function serializeGraph(graph: SkillGraph): string {
|
||||
const serialized = {
|
||||
version: graph.version,
|
||||
generatedAt: graph.generatedAt,
|
||||
totalSkills: graph.totalSkills,
|
||||
totalRelations: graph.totalRelations,
|
||||
nodes: Object.fromEntries(graph.nodes),
|
||||
};
|
||||
return JSON.stringify(serialized, null, 2);
|
||||
}
|
||||
|
||||
export function deserializeGraph(json: string): SkillGraph {
|
||||
const parsed = JSON.parse(json);
|
||||
return {
|
||||
version: parsed.version,
|
||||
generatedAt: parsed.generatedAt,
|
||||
totalSkills: parsed.totalSkills,
|
||||
totalRelations: parsed.totalRelations,
|
||||
nodes: new Map(Object.entries(parsed.nodes)),
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,25 @@
|
||||
export * from './types.js';
|
||||
export * from './generator.js';
|
||||
export * from './serializer.js';
|
||||
export * from './graph.js';
|
||||
|
||||
export { TreeGenerator, generateSkillTree } from './generator.js';
|
||||
export {
|
||||
serializeTree,
|
||||
deserializeTree,
|
||||
saveTree,
|
||||
loadTree,
|
||||
treeToText,
|
||||
treeToMarkdown,
|
||||
compareTreeVersions,
|
||||
TREE_FILE_NAME,
|
||||
} from './serializer.js';
|
||||
export {
|
||||
buildSkillGraph,
|
||||
getRelatedSkills,
|
||||
findSkillsByRelationType,
|
||||
getSkillPath,
|
||||
findSkillsInCategory,
|
||||
serializeGraph,
|
||||
deserializeGraph,
|
||||
} from './graph.js';
|
||||
@@ -0,0 +1,191 @@
|
||||
import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
|
||||
import { dirname } from 'node:path';
|
||||
import type { SkillTree, TreeNode } from './types.js';
|
||||
import { SkillTreeSchema } from './types.js';
|
||||
|
||||
export const TREE_FILE_NAME = 'skill-tree.json';
|
||||
|
||||
export function serializeTree(tree: SkillTree): string {
|
||||
return JSON.stringify(tree, null, 2);
|
||||
}
|
||||
|
||||
export function deserializeTree(json: string): SkillTree {
|
||||
const parsed = JSON.parse(json);
|
||||
return SkillTreeSchema.parse(parsed);
|
||||
}
|
||||
|
||||
export function saveTree(tree: SkillTree, path: string): void {
|
||||
const dir = dirname(path);
|
||||
if (!existsSync(dir)) {
|
||||
mkdirSync(dir, { recursive: true });
|
||||
}
|
||||
|
||||
const json = serializeTree(tree);
|
||||
writeFileSync(path, json, 'utf-8');
|
||||
}
|
||||
|
||||
export function loadTree(path: string): SkillTree | null {
|
||||
if (!existsSync(path)) {
|
||||
return null;
|
||||
}
|
||||
|
||||
try {
|
||||
const json = readFileSync(path, 'utf-8');
|
||||
return deserializeTree(json);
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
export function treeToText(tree: SkillTree, options?: { maxDepth?: number }): string {
|
||||
const maxDepth = options?.maxDepth ?? Infinity;
|
||||
const lines: string[] = [];
|
||||
|
||||
lines.push(`Skill Tree (${tree.totalSkills} skills, ${tree.totalCategories} categories)`);
|
||||
lines.push(`Generated: ${tree.generatedAt}`);
|
||||
lines.push('');
|
||||
|
||||
const renderNode = (node: TreeNode, prefix: string, isLast: boolean, depth: number) => {
|
||||
if (depth > maxDepth) return;
|
||||
|
||||
const connector = isLast ? '└── ' : '├── ';
|
||||
const skillInfo =
|
||||
node.skillCount > 0 ? ` (${node.skillCount} skills)` : '';
|
||||
|
||||
lines.push(`${prefix}${connector}${node.name}${skillInfo}`);
|
||||
|
||||
const newPrefix = prefix + (isLast ? ' ' : '│ ');
|
||||
|
||||
if (node.children.length > 0 && depth < maxDepth) {
|
||||
node.children.forEach((child, index) => {
|
||||
const childIsLast = index === node.children.length - 1;
|
||||
renderNode(child, newPrefix, childIsLast, depth + 1);
|
||||
});
|
||||
}
|
||||
};
|
||||
|
||||
const root = tree.rootNode;
|
||||
lines.push(root.name);
|
||||
|
||||
root.children.forEach((child, index) => {
|
||||
const isLast = index === root.children.length - 1;
|
||||
renderNode(child, '', isLast, 1);
|
||||
});
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
export function treeToMarkdown(tree: SkillTree): string {
|
||||
const lines: string[] = [];
|
||||
|
||||
lines.push(`# Skill Tree`);
|
||||
lines.push('');
|
||||
lines.push(`> ${tree.totalSkills} skills organized in ${tree.totalCategories} categories`);
|
||||
lines.push('');
|
||||
lines.push(`*Generated: ${tree.generatedAt}*`);
|
||||
lines.push('');
|
||||
|
||||
const renderNode = (node: TreeNode, depth: number) => {
|
||||
const indent = ' '.repeat(depth);
|
||||
const bullet = depth === 0 ? '##' : '-';
|
||||
|
||||
if (depth === 0) {
|
||||
lines.push(`${bullet} ${node.name}`);
|
||||
} else {
|
||||
const skillCount = node.skillCount > 0 ? ` *(${node.skillCount})*` : '';
|
||||
lines.push(`${indent}${bullet} **${node.name}**${skillCount}`);
|
||||
}
|
||||
|
||||
if (node.skills.length > 0 && node.skills.length <= 10) {
|
||||
for (const skill of node.skills) {
|
||||
lines.push(`${indent} - \`${skill}\``);
|
||||
}
|
||||
} else if (node.skills.length > 10) {
|
||||
for (const skill of node.skills.slice(0, 5)) {
|
||||
lines.push(`${indent} - \`${skill}\``);
|
||||
}
|
||||
lines.push(`${indent} - *... and ${node.skills.length - 5} more*`);
|
||||
}
|
||||
|
||||
for (const child of node.children) {
|
||||
renderNode(child, depth + 1);
|
||||
}
|
||||
};
|
||||
|
||||
for (const category of tree.rootNode.children) {
|
||||
renderNode(category, 0);
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
export function compareTreeVersions(
|
||||
oldTree: SkillTree,
|
||||
newTree: SkillTree
|
||||
): {
|
||||
added: string[];
|
||||
removed: string[];
|
||||
moved: { skill: string; from: string[]; to: string[] }[];
|
||||
} {
|
||||
const oldSkills = getAllSkillsWithPaths(oldTree.rootNode);
|
||||
const newSkills = getAllSkillsWithPaths(newTree.rootNode);
|
||||
|
||||
const oldNames = new Set(oldSkills.map((s) => s.name));
|
||||
const newNames = new Set(newSkills.map((s) => s.name));
|
||||
|
||||
const added: string[] = [];
|
||||
const removed: string[] = [];
|
||||
const moved: { skill: string; from: string[]; to: string[] }[] = [];
|
||||
|
||||
for (const skill of newSkills) {
|
||||
if (!oldNames.has(skill.name)) {
|
||||
added.push(skill.name);
|
||||
}
|
||||
}
|
||||
|
||||
for (const skill of oldSkills) {
|
||||
if (!newNames.has(skill.name)) {
|
||||
removed.push(skill.name);
|
||||
}
|
||||
}
|
||||
|
||||
for (const newSkill of newSkills) {
|
||||
const oldSkill = oldSkills.find((s) => s.name === newSkill.name);
|
||||
if (oldSkill && !arraysEqual(oldSkill.path, newSkill.path)) {
|
||||
moved.push({
|
||||
skill: newSkill.name,
|
||||
from: oldSkill.path,
|
||||
to: newSkill.path,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
return { added, removed, moved };
|
||||
}
|
||||
|
||||
function getAllSkillsWithPaths(
|
||||
node: TreeNode,
|
||||
currentPath: string[] = []
|
||||
): { name: string; path: string[] }[] {
|
||||
const results: { name: string; path: string[] }[] = [];
|
||||
const path = [...currentPath, node.name];
|
||||
|
||||
for (const skill of node.skills) {
|
||||
results.push({ name: skill, path });
|
||||
}
|
||||
|
||||
for (const child of node.children) {
|
||||
results.push(...getAllSkillsWithPaths(child, path));
|
||||
}
|
||||
|
||||
return results;
|
||||
}
|
||||
|
||||
function arraysEqual(a: string[], b: string[]): boolean {
|
||||
if (a.length !== b.length) return false;
|
||||
for (let i = 0; i < a.length; i++) {
|
||||
if (a[i] !== b[i]) return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
@@ -0,0 +1,142 @@
|
||||
import { z } from 'zod';
|
||||
|
||||
const BaseTreeNodeSchema = z.object({
|
||||
id: z.string(),
|
||||
name: z.string(),
|
||||
description: z.string().optional(),
|
||||
skills: z.array(z.string()).default([]),
|
||||
skillCount: z.number().default(0),
|
||||
depth: z.number().default(0),
|
||||
});
|
||||
|
||||
export interface TreeNode {
|
||||
id: string;
|
||||
name: string;
|
||||
description?: string;
|
||||
children: TreeNode[];
|
||||
skills: string[];
|
||||
skillCount: number;
|
||||
depth: number;
|
||||
}
|
||||
|
||||
export const TreeNodeSchema: z.ZodType<TreeNode> = BaseTreeNodeSchema.extend({
|
||||
children: z.lazy(() => z.array(TreeNodeSchema)).default([]),
|
||||
}) as z.ZodType<TreeNode>;
|
||||
|
||||
export const SkillTreeSchema = z.object({
|
||||
version: z.number().default(1),
|
||||
generatedAt: z.string(),
|
||||
rootNode: TreeNodeSchema,
|
||||
totalSkills: z.number(),
|
||||
totalCategories: z.number(),
|
||||
maxDepth: z.number(),
|
||||
});
|
||||
|
||||
export type SkillTree = z.infer<typeof SkillTreeSchema>;
|
||||
|
||||
export interface TreePath {
|
||||
segments: string[];
|
||||
node: TreeNode;
|
||||
}
|
||||
|
||||
export interface CategoryMapping {
|
||||
category: string;
|
||||
subcategories: string[];
|
||||
tags: string[];
|
||||
keywords: string[];
|
||||
}
|
||||
|
||||
export const CATEGORY_TAXONOMY: CategoryMapping[] = [
|
||||
{
|
||||
category: 'Development',
|
||||
subcategories: ['Frontend', 'Backend', 'Mobile', 'Desktop', 'Full-Stack'],
|
||||
tags: ['development', 'coding', 'programming', 'software'],
|
||||
keywords: ['build', 'create', 'develop', 'code', 'implement'],
|
||||
},
|
||||
{
|
||||
category: 'Frontend',
|
||||
subcategories: ['React', 'Vue', 'Angular', 'Svelte', 'Solid', 'Astro', 'Next.js', 'Nuxt', 'Remix'],
|
||||
tags: ['frontend', 'ui', 'ux', 'web', 'client', 'browser', 'react', 'vue', 'angular', 'svelte', 'solid', 'astro', 'nextjs', 'nuxt', 'remix'],
|
||||
keywords: ['component', 'ui', 'interface', 'layout', 'style', 'css', 'html'],
|
||||
},
|
||||
{
|
||||
category: 'Backend',
|
||||
subcategories: ['Node.js', 'Python', 'Go', 'Rust', 'Java', 'C#', 'Express', 'FastAPI', 'Django', 'Flask'],
|
||||
tags: ['backend', 'server', 'api', 'node', 'nodejs', 'python', 'go', 'rust', 'java', 'express', 'fastapi', 'django', 'flask', 'fastify', 'koa', 'hono', 'nestjs'],
|
||||
keywords: ['server', 'api', 'endpoint', 'route', 'handler', 'middleware'],
|
||||
},
|
||||
{
|
||||
category: 'Mobile',
|
||||
subcategories: ['React Native', 'Flutter', 'iOS', 'Android', 'Expo'],
|
||||
tags: ['mobile', 'ios', 'android', 'react-native', 'flutter', 'expo', 'native'],
|
||||
keywords: ['app', 'mobile', 'phone', 'tablet', 'native'],
|
||||
},
|
||||
{
|
||||
category: 'DevOps',
|
||||
subcategories: ['CI/CD', 'Kubernetes', 'Docker', 'Cloud', 'Infrastructure'],
|
||||
tags: ['devops', 'ci', 'cd', 'cicd', 'kubernetes', 'k8s', 'docker', 'container', 'aws', 'gcp', 'azure', 'cloud', 'infrastructure', 'iac'],
|
||||
keywords: ['deploy', 'pipeline', 'container', 'orchestration', 'infra'],
|
||||
},
|
||||
{
|
||||
category: 'Testing',
|
||||
subcategories: ['Unit Testing', 'E2E Testing', 'Integration Testing', 'TDD'],
|
||||
tags: ['testing', 'test', 'unit', 'e2e', 'integration', 'jest', 'vitest', 'playwright', 'cypress', 'tdd'],
|
||||
keywords: ['test', 'spec', 'assertion', 'mock', 'coverage'],
|
||||
},
|
||||
{
|
||||
category: 'Security',
|
||||
subcategories: ['Authentication', 'Authorization', 'Encryption', 'Audit'],
|
||||
tags: ['security', 'auth', 'authentication', 'authorization', 'oauth', 'jwt', 'encryption', 'audit', 'vulnerability'],
|
||||
keywords: ['secure', 'protect', 'encrypt', 'authenticate', 'authorize'],
|
||||
},
|
||||
{
|
||||
category: 'AI/ML',
|
||||
subcategories: ['LLM Integration', 'Agents', 'RAG', 'Training', 'Inference'],
|
||||
tags: ['ai', 'ml', 'llm', 'openai', 'anthropic', 'gpt', 'claude', 'agent', 'rag', 'embedding', 'vector', 'training', 'inference'],
|
||||
keywords: ['ai', 'model', 'predict', 'generate', 'embed', 'chat'],
|
||||
},
|
||||
{
|
||||
category: 'Database',
|
||||
subcategories: ['SQL', 'NoSQL', 'ORM', 'Migrations'],
|
||||
tags: ['database', 'db', 'sql', 'nosql', 'postgres', 'postgresql', 'mysql', 'mongodb', 'redis', 'supabase', 'firebase', 'prisma', 'drizzle'],
|
||||
keywords: ['query', 'schema', 'migration', 'model', 'record'],
|
||||
},
|
||||
{
|
||||
category: 'Tooling',
|
||||
subcategories: ['Linting', 'Formatting', 'Building', 'Bundling'],
|
||||
tags: ['tooling', 'tool', 'eslint', 'prettier', 'biome', 'webpack', 'vite', 'rollup', 'turbo', 'turborepo', 'monorepo'],
|
||||
keywords: ['lint', 'format', 'build', 'bundle', 'compile'],
|
||||
},
|
||||
{
|
||||
category: 'Documentation',
|
||||
subcategories: ['API Docs', 'Guides', 'READMEs', 'Comments'],
|
||||
tags: ['documentation', 'docs', 'readme', 'api-docs', 'jsdoc', 'typedoc', 'storybook'],
|
||||
keywords: ['doc', 'document', 'guide', 'readme', 'comment'],
|
||||
},
|
||||
{
|
||||
category: 'Performance',
|
||||
subcategories: ['Optimization', 'Caching', 'Profiling', 'Monitoring'],
|
||||
tags: ['performance', 'optimization', 'cache', 'caching', 'profiling', 'monitoring', 'metrics', 'observability'],
|
||||
keywords: ['optimize', 'fast', 'cache', 'profile', 'monitor'],
|
||||
},
|
||||
];
|
||||
|
||||
export const TAG_TO_CATEGORY: Record<string, string[]> = {};
|
||||
|
||||
for (const mapping of CATEGORY_TAXONOMY) {
|
||||
for (const tag of mapping.tags) {
|
||||
if (!TAG_TO_CATEGORY[tag]) {
|
||||
TAG_TO_CATEGORY[tag] = [];
|
||||
}
|
||||
TAG_TO_CATEGORY[tag].push(mapping.category);
|
||||
for (const subcategory of mapping.subcategories) {
|
||||
TAG_TO_CATEGORY[tag].push(`${mapping.category} > ${subcategory}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export interface TreeGeneratorOptions {
|
||||
maxDepth?: number;
|
||||
minSkillsPerNode?: number;
|
||||
includeEmpty?: boolean;
|
||||
}
|
||||
@@ -36,7 +36,7 @@ export const AgentType = z.enum([
|
||||
]);
|
||||
export type AgentType = z.infer<typeof AgentType>;
|
||||
|
||||
export const GitProvider = z.enum(['github', 'gitlab', 'bitbucket', 'local']);
|
||||
export const GitProvider = z.enum(['github', 'gitlab', 'bitbucket', 'local', 'wellknown']);
|
||||
export type GitProvider = z.infer<typeof GitProvider>;
|
||||
|
||||
export const SkillFrontmatter = z.object({
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@skillkit/mcp-memory",
|
||||
"version": "1.8.0",
|
||||
"version": "1.10.0",
|
||||
"description": "MCP (Model Context Protocol) server for SkillKit persistent memory",
|
||||
"type": "module",
|
||||
"main": "./dist/index.js",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@skillkit/memory",
|
||||
"version": "1.8.0",
|
||||
"version": "1.10.0",
|
||||
"description": "CozoDB-backed semantic memory with embeddings for SkillKit",
|
||||
"type": "module",
|
||||
"main": "./dist/index.js",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@skillkit/mesh",
|
||||
"version": "1.8.0",
|
||||
"version": "1.10.0",
|
||||
"description": "Peer mesh network for multi-machine agent distribution",
|
||||
"type": "module",
|
||||
"main": "./dist/index.js",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@skillkit/messaging",
|
||||
"version": "1.8.0",
|
||||
"version": "1.10.0",
|
||||
"description": "Inter-agent messaging system for SkillKit",
|
||||
"type": "module",
|
||||
"main": "./dist/index.js",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@skillkit/resources",
|
||||
"version": "1.8.0",
|
||||
"version": "1.10.0",
|
||||
"description": "Bundled resources for SkillKit - agents, commands, profiles, guidelines, and hooks",
|
||||
"type": "module",
|
||||
"main": "./dist/index.js",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@skillkit/tui",
|
||||
"version": "1.8.0",
|
||||
"version": "1.10.0",
|
||||
"description": "Unified Terminal UI for SkillKit - Built on OpenTUI",
|
||||
"type": "module",
|
||||
"main": "./dist/index.js",
|
||||
@@ -21,15 +21,15 @@
|
||||
"test": "vitest run"
|
||||
},
|
||||
"dependencies": {
|
||||
"@skillkit/core": "workspace:*",
|
||||
"@skillkit/agents": "workspace:*",
|
||||
"@opentui/core": "^0.1.75",
|
||||
"@opentui/react": "^0.1.75",
|
||||
"react": "^19.0.0"
|
||||
"@opentui/solid": "^0.1.75",
|
||||
"@skillkit/agents": "workspace:*",
|
||||
"@skillkit/core": "workspace:*",
|
||||
"solid-js": "^1.9.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/node": "^22.10.5",
|
||||
"@types/react": "^19.0.0",
|
||||
"esbuild-plugin-solid": "^0.6.0",
|
||||
"tsup": "^8.3.5",
|
||||
"typescript": "^5.7.2",
|
||||
"vitest": "^2.1.8"
|
||||
|
||||
+91
-67
@@ -1,9 +1,10 @@
|
||||
import { useState, useCallback, useEffect } from 'react';
|
||||
import { useKeyboard } from '@opentui/react';
|
||||
import { exec } from 'node:child_process';
|
||||
import { createSignal, createEffect, onCleanup, Show, Switch, Match } from 'solid-js';
|
||||
import { useKeyboard } from '@opentui/solid';
|
||||
import { execFile } from 'node:child_process';
|
||||
import { type Screen, NAV_KEYS } from './state/types.js';
|
||||
import { Sidebar } from './components/Sidebar.js';
|
||||
import { Splash } from './components/Splash.js';
|
||||
import { Sidebar } from './components/Sidebar.js';
|
||||
import { StatusBar } from './components/StatusBar.js';
|
||||
import {
|
||||
Home, Browse, Installed, Marketplace, Settings, Recommend,
|
||||
Translate, Context, Memory, Team, Plugins, Methodology,
|
||||
@@ -13,23 +14,28 @@ import {
|
||||
const DOCS_URL = 'https://agenstskills.com/docs';
|
||||
|
||||
function openUrl(url: string): void {
|
||||
const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
|
||||
exec(`${cmd} ${url}`);
|
||||
if (process.platform === 'win32') {
|
||||
execFile('cmd', ['/c', 'start', '', url]);
|
||||
} else {
|
||||
const cmd = process.platform === 'darwin' ? 'open' : 'xdg-open';
|
||||
execFile(cmd, [url]);
|
||||
}
|
||||
}
|
||||
|
||||
interface AppProps {
|
||||
onExit?: (code?: number) => void;
|
||||
}
|
||||
|
||||
export function App({ onExit }: AppProps = {}) {
|
||||
const [showSplash, setShowSplash] = useState(true);
|
||||
const [screen, setScreen] = useState<Screen>('home');
|
||||
const [dimensions, setDimensions] = useState({
|
||||
export function App(props: AppProps) {
|
||||
const [showSplash, setShowSplash] = createSignal(true);
|
||||
const [currentScreen, setCurrentScreen] = createSignal<Screen>('home');
|
||||
const [showSidebar, setShowSidebar] = createSignal(true);
|
||||
const [dimensions, setDimensions] = createSignal({
|
||||
cols: process.stdout.columns || 80,
|
||||
rows: process.stdout.rows || 24,
|
||||
});
|
||||
|
||||
useEffect(() => {
|
||||
createEffect(() => {
|
||||
const handleResize = () => {
|
||||
setDimensions({
|
||||
cols: process.stdout.columns || 80,
|
||||
@@ -37,28 +43,38 @@ export function App({ onExit }: AppProps = {}) {
|
||||
});
|
||||
};
|
||||
process.stdout.on('resize', handleResize);
|
||||
return () => { process.stdout.off('resize', handleResize); };
|
||||
}, []);
|
||||
onCleanup(() => {
|
||||
process.stdout.off('resize', handleResize);
|
||||
});
|
||||
});
|
||||
|
||||
const { cols, rows } = dimensions;
|
||||
const showSidebar = cols >= 60;
|
||||
const cols = () => dimensions().cols;
|
||||
const rows = () => dimensions().rows;
|
||||
const sidebarVisible = () => showSidebar() && cols() >= 80;
|
||||
const sidebarWidth = () => {
|
||||
if (!sidebarVisible()) return 0;
|
||||
if (cols() >= 100) return 24;
|
||||
return 18;
|
||||
};
|
||||
const statusBarHeight = 2;
|
||||
const contentHeight = () => rows() - statusBarHeight;
|
||||
|
||||
const handleNavigate = useCallback((newScreen: Screen) => {
|
||||
setScreen(newScreen);
|
||||
}, []);
|
||||
const handleNavigate = (newScreen: Screen) => {
|
||||
setCurrentScreen(newScreen);
|
||||
};
|
||||
|
||||
const handleSplashComplete = useCallback(() => {
|
||||
const handleSplashComplete = () => {
|
||||
setShowSplash(false);
|
||||
}, []);
|
||||
};
|
||||
|
||||
useKeyboard((key: { name?: string; ctrl?: boolean }) => {
|
||||
if (showSplash) {
|
||||
useKeyboard((key: { name?: string; ctrl?: boolean; sequence?: string }) => {
|
||||
if (showSplash()) {
|
||||
setShowSplash(false);
|
||||
return;
|
||||
}
|
||||
|
||||
if (key.name === 'q' || (key.ctrl && key.name === 'c')) {
|
||||
onExit ? onExit(0) : process.exit(0);
|
||||
props.onExit ? props.onExit(0) : process.exit(0);
|
||||
return;
|
||||
}
|
||||
|
||||
@@ -67,59 +83,67 @@ export function App({ onExit }: AppProps = {}) {
|
||||
return;
|
||||
}
|
||||
|
||||
const targetScreen = NAV_KEYS[key.name || ''];
|
||||
if (targetScreen) {
|
||||
setScreen(targetScreen);
|
||||
if (key.sequence === '\\') {
|
||||
setShowSidebar((v) => !v);
|
||||
return;
|
||||
}
|
||||
|
||||
if (key.name === 'escape' && screen !== 'home') {
|
||||
setScreen('home');
|
||||
const targetScreen = NAV_KEYS[key.name || ''];
|
||||
if (targetScreen) {
|
||||
setCurrentScreen(targetScreen);
|
||||
}
|
||||
|
||||
if (key.name === 'escape' && currentScreen() !== 'home') {
|
||||
setCurrentScreen('home');
|
||||
}
|
||||
});
|
||||
|
||||
if (showSplash) {
|
||||
return <Splash onComplete={handleSplashComplete} duration={3000} />;
|
||||
}
|
||||
|
||||
const screenProps = {
|
||||
const screenProps = () => ({
|
||||
onNavigate: handleNavigate,
|
||||
cols: cols - (showSidebar ? 20 : 0),
|
||||
rows,
|
||||
};
|
||||
|
||||
const renderScreen = () => {
|
||||
switch (screen) {
|
||||
case 'home': return <Home {...screenProps} />;
|
||||
case 'browse': return <Browse {...screenProps} />;
|
||||
case 'installed': return <Installed {...screenProps} />;
|
||||
case 'marketplace': return <Marketplace {...screenProps} />;
|
||||
case 'settings': return <Settings {...screenProps} />;
|
||||
case 'recommend': return <Recommend {...screenProps} />;
|
||||
case 'translate': return <Translate {...screenProps} />;
|
||||
case 'context': return <Context {...screenProps} />;
|
||||
case 'memory': return <Memory {...screenProps} />;
|
||||
case 'team': return <Team {...screenProps} />;
|
||||
case 'plugins': return <Plugins {...screenProps} />;
|
||||
case 'methodology': return <Methodology {...screenProps} />;
|
||||
case 'plan': return <Plan {...screenProps} />;
|
||||
case 'workflow': return <Workflow {...screenProps} />;
|
||||
case 'execute': return <Execute {...screenProps} />;
|
||||
case 'history': return <History {...screenProps} />;
|
||||
case 'sync': return <Sync {...screenProps} />;
|
||||
case 'help': return <Help {...screenProps} />;
|
||||
case 'mesh': return <Mesh {...screenProps} />;
|
||||
case 'message': return <Message {...screenProps} />;
|
||||
default: return <Home {...screenProps} />;
|
||||
}
|
||||
};
|
||||
cols: Math.max(1, cols() - sidebarWidth() - 2),
|
||||
rows: Math.max(1, contentHeight() - 1),
|
||||
});
|
||||
|
||||
return (
|
||||
<box flexDirection="row" height={rows}>
|
||||
{showSidebar && <Sidebar screen={screen} onNavigate={handleNavigate} />}
|
||||
<box flexDirection="column" flexGrow={1} marginLeft={showSidebar ? 1 : 0} paddingRight={1}>
|
||||
{renderScreen()}
|
||||
<Show when={!showSplash()} fallback={<Splash onComplete={handleSplashComplete} duration={3000} />}>
|
||||
<box flexDirection="column" height={rows()}>
|
||||
<box flexDirection="row" height={contentHeight()}>
|
||||
<Show when={sidebarVisible()}>
|
||||
<Sidebar
|
||||
screen={currentScreen()}
|
||||
onNavigate={handleNavigate}
|
||||
/>
|
||||
</Show>
|
||||
|
||||
<box flexDirection="column" flexGrow={1} paddingX={1}>
|
||||
<Switch fallback={<Home {...screenProps()} />}>
|
||||
<Match when={currentScreen() === 'home'}><Home {...screenProps()} /></Match>
|
||||
<Match when={currentScreen() === 'browse'}><Browse {...screenProps()} /></Match>
|
||||
<Match when={currentScreen() === 'installed'}><Installed {...screenProps()} /></Match>
|
||||
<Match when={currentScreen() === 'marketplace'}><Marketplace {...screenProps()} /></Match>
|
||||
<Match when={currentScreen() === 'settings'}><Settings {...screenProps()} /></Match>
|
||||
<Match when={currentScreen() === 'recommend'}><Recommend {...screenProps()} /></Match>
|
||||
<Match when={currentScreen() === 'translate'}><Translate {...screenProps()} /></Match>
|
||||
<Match when={currentScreen() === 'context'}><Context {...screenProps()} /></Match>
|
||||
<Match when={currentScreen() === 'memory'}><Memory {...screenProps()} /></Match>
|
||||
<Match when={currentScreen() === 'team'}><Team {...screenProps()} /></Match>
|
||||
<Match when={currentScreen() === 'plugins'}><Plugins {...screenProps()} /></Match>
|
||||
<Match when={currentScreen() === 'methodology'}><Methodology {...screenProps()} /></Match>
|
||||
<Match when={currentScreen() === 'plan'}><Plan {...screenProps()} /></Match>
|
||||
<Match when={currentScreen() === 'workflow'}><Workflow {...screenProps()} /></Match>
|
||||
<Match when={currentScreen() === 'execute'}><Execute {...screenProps()} /></Match>
|
||||
<Match when={currentScreen() === 'history'}><History {...screenProps()} /></Match>
|
||||
<Match when={currentScreen() === 'sync'}><Sync {...screenProps()} /></Match>
|
||||
<Match when={currentScreen() === 'help'}><Help {...screenProps()} /></Match>
|
||||
<Match when={currentScreen() === 'mesh'}><Mesh {...screenProps()} /></Match>
|
||||
<Match when={currentScreen() === 'message'}><Message {...screenProps()} /></Match>
|
||||
</Switch>
|
||||
</box>
|
||||
</box>
|
||||
|
||||
<StatusBar />
|
||||
</box>
|
||||
</box>
|
||||
</Show>
|
||||
);
|
||||
}
|
||||
|
||||
|
||||
@@ -1,36 +1,32 @@
|
||||
/**
|
||||
* AgentGrid Component
|
||||
* Displays monochromatic agent logos in a grid layout
|
||||
*/
|
||||
import { Show, For, createMemo } from 'solid-js';
|
||||
import { AGENT_LOGOS, type AgentLogo } from '../theme/symbols.js';
|
||||
import { terminalColors } from '../theme/colors.js';
|
||||
|
||||
interface AgentGridProps {
|
||||
/** Maximum number of agents to display */
|
||||
maxVisible?: number;
|
||||
/** Show status indicators for detected agents */
|
||||
showStatus?: boolean;
|
||||
/** Agent types that are detected/active */
|
||||
detectedAgents?: string[];
|
||||
/** Number of columns in the grid */
|
||||
columns?: number;
|
||||
}
|
||||
|
||||
export function AgentGrid({
|
||||
maxVisible = 12,
|
||||
showStatus = true,
|
||||
detectedAgents = [],
|
||||
columns = 4,
|
||||
}: AgentGridProps) {
|
||||
const safeColumns = Math.max(1, columns);
|
||||
const allAgents = Object.entries(AGENT_LOGOS);
|
||||
const visibleAgents = allAgents.slice(0, maxVisible);
|
||||
const hiddenCount = allAgents.length - maxVisible;
|
||||
export function AgentGrid(props: AgentGridProps) {
|
||||
const maxVisible = () => props.maxVisible ?? 12;
|
||||
const showStatus = () => props.showStatus ?? true;
|
||||
const detectedAgents = () => props.detectedAgents ?? [];
|
||||
const columns = () => Math.max(1, props.columns ?? 4);
|
||||
|
||||
const rows: [string, AgentLogo][][] = [];
|
||||
for (let i = 0; i < visibleAgents.length; i += safeColumns) {
|
||||
rows.push(visibleAgents.slice(i, i + safeColumns));
|
||||
}
|
||||
const allAgents = Object.entries(AGENT_LOGOS);
|
||||
const visibleAgents = () => allAgents.slice(0, maxVisible());
|
||||
const hiddenCount = () => allAgents.length - maxVisible();
|
||||
|
||||
const rows = createMemo((): [string, AgentLogo][][] => {
|
||||
const result: [string, AgentLogo][][] = [];
|
||||
const visible = visibleAgents();
|
||||
for (let i = 0; i < visible.length; i += columns()) {
|
||||
result.push(visible.slice(i, i + columns()));
|
||||
}
|
||||
return result;
|
||||
});
|
||||
|
||||
return (
|
||||
<box flexDirection="column">
|
||||
@@ -38,31 +34,36 @@ export function AgentGrid({
|
||||
<b>Works with</b>
|
||||
</text>
|
||||
<text> </text>
|
||||
{rows.map((row, rowIndex) => (
|
||||
<box key={`row-${rowIndex}`} flexDirection="row">
|
||||
{row.map(([agentType, agent]) => {
|
||||
const isDetected = detectedAgents.includes(agentType);
|
||||
const statusIcon = showStatus ? (isDetected ? '●' : '○') : '';
|
||||
const fg = isDetected ? terminalColors.accent : terminalColors.text;
|
||||
<For each={rows()}>
|
||||
{(row, rowIndex) => (
|
||||
<box flexDirection="row">
|
||||
<For each={row}>
|
||||
{([agentType, agent]) => {
|
||||
const isDetected = () => detectedAgents().includes(agentType);
|
||||
const statusIcon = () => (showStatus() ? (isDetected() ? '●' : '○') : '');
|
||||
const fg = () => (isDetected() ? terminalColors.accent : terminalColors.text);
|
||||
|
||||
return (
|
||||
<box key={agentType} width={18}>
|
||||
<text fg={fg}>
|
||||
{agent.icon} {agent.name}
|
||||
{showStatus && (
|
||||
<span fg={isDetected ? terminalColors.success : terminalColors.textMuted}>
|
||||
{' '}{statusIcon}
|
||||
</span>
|
||||
)}
|
||||
</text>
|
||||
</box>
|
||||
);
|
||||
})}
|
||||
</box>
|
||||
))}
|
||||
{hiddenCount > 0 && (
|
||||
<text fg={terminalColors.textMuted}>+{hiddenCount} more agents</text>
|
||||
)}
|
||||
return (
|
||||
<box width={18}>
|
||||
<text fg={fg()}>
|
||||
{agent.icon} {agent.name}
|
||||
<Show when={showStatus()}>
|
||||
<span fg={isDetected() ? terminalColors.success : terminalColors.textMuted}>
|
||||
{' '}
|
||||
{statusIcon()}
|
||||
</span>
|
||||
</Show>
|
||||
</text>
|
||||
</box>
|
||||
);
|
||||
}}
|
||||
</For>
|
||||
</box>
|
||||
)}
|
||||
</For>
|
||||
<Show when={hiddenCount() > 0}>
|
||||
<text fg={terminalColors.textMuted}>+{hiddenCount()} more agents</text>
|
||||
</Show>
|
||||
</box>
|
||||
);
|
||||
}
|
||||
|
||||
@@ -0,0 +1,234 @@
|
||||
/**
|
||||
* AnimatedText Component
|
||||
* Text with fade/slide animations
|
||||
*/
|
||||
|
||||
import { Show, createSignal, createEffect, onCleanup } from 'solid-js';
|
||||
import { terminalColors } from '../theme/colors.js';
|
||||
import { scrambleText } from '../theme/animations.js';
|
||||
|
||||
interface AnimatedTextProps {
|
||||
text: string;
|
||||
animation?: 'fadeIn' | 'typewriter' | 'scramble' | 'countUp' | 'none';
|
||||
duration?: number;
|
||||
delay?: number;
|
||||
color?: string;
|
||||
onComplete?: () => void;
|
||||
}
|
||||
|
||||
export function AnimatedText(props: AnimatedTextProps) {
|
||||
const [progress, setProgress] = createSignal(0);
|
||||
const [isComplete, setIsComplete] = createSignal(false);
|
||||
|
||||
const animation = () => props.animation ?? 'fadeIn';
|
||||
const duration = () => Math.max(1, props.duration ?? 500);
|
||||
const delay = () => Math.max(0, props.delay ?? 0);
|
||||
const color = () => props.color ?? terminalColors.text;
|
||||
|
||||
createEffect(() => {
|
||||
const anim = animation();
|
||||
const dur = duration();
|
||||
const dly = delay();
|
||||
|
||||
setProgress(0);
|
||||
setIsComplete(false);
|
||||
|
||||
if (anim === 'none') {
|
||||
setProgress(100);
|
||||
setIsComplete(true);
|
||||
return;
|
||||
}
|
||||
|
||||
let delayTimeoutId: ReturnType<typeof setTimeout> | undefined;
|
||||
let animationTimeoutId: ReturnType<typeof setTimeout> | undefined;
|
||||
let startTime: number | undefined;
|
||||
let cancelled = false;
|
||||
|
||||
const animate = () => {
|
||||
if (cancelled) return;
|
||||
|
||||
const now = Date.now();
|
||||
if (!startTime) startTime = now;
|
||||
const elapsed = now - startTime;
|
||||
const p = Math.min((elapsed / dur) * 100, 100);
|
||||
|
||||
setProgress(p);
|
||||
|
||||
if (p < 100) {
|
||||
animationTimeoutId = setTimeout(animate, 16);
|
||||
} else {
|
||||
setIsComplete(true);
|
||||
props.onComplete?.();
|
||||
}
|
||||
};
|
||||
|
||||
if (dly > 0) {
|
||||
delayTimeoutId = setTimeout(() => {
|
||||
animationTimeoutId = setTimeout(animate, 16);
|
||||
}, dly);
|
||||
} else {
|
||||
animationTimeoutId = setTimeout(animate, 16);
|
||||
}
|
||||
|
||||
onCleanup(() => {
|
||||
cancelled = true;
|
||||
if (delayTimeoutId) clearTimeout(delayTimeoutId);
|
||||
if (animationTimeoutId) clearTimeout(animationTimeoutId);
|
||||
});
|
||||
});
|
||||
|
||||
const displayText = () => {
|
||||
switch (animation()) {
|
||||
case 'typewriter': {
|
||||
const charCount = Math.floor((progress() / 100) * props.text.length);
|
||||
return props.text.slice(0, charCount);
|
||||
}
|
||||
case 'scramble': {
|
||||
return scrambleText(props.text, progress());
|
||||
}
|
||||
case 'countUp': {
|
||||
const num = parseFloat(props.text);
|
||||
if (!isNaN(num)) {
|
||||
return String(Math.round((progress() / 100) * num));
|
||||
}
|
||||
return props.text;
|
||||
}
|
||||
case 'fadeIn':
|
||||
case 'none':
|
||||
default:
|
||||
return props.text;
|
||||
}
|
||||
};
|
||||
|
||||
return (
|
||||
<text fg={color()}>
|
||||
{displayText()}
|
||||
<Show when={animation() === 'typewriter' && !isComplete()}>
|
||||
<text fg={terminalColors.accent}>▌</text>
|
||||
</Show>
|
||||
</text>
|
||||
);
|
||||
}
|
||||
|
||||
interface CountUpTextProps {
|
||||
value: number;
|
||||
duration?: number;
|
||||
delay?: number;
|
||||
prefix?: string;
|
||||
suffix?: string;
|
||||
color?: string;
|
||||
formatter?: (value: number) => string;
|
||||
}
|
||||
|
||||
export function CountUpText(props: CountUpTextProps) {
|
||||
const [displayValue, setDisplayValue] = createSignal(0);
|
||||
const duration = () => Math.max(1, props.duration ?? 1000);
|
||||
const delay = () => Math.max(0, props.delay ?? 0);
|
||||
const color = () => props.color ?? terminalColors.text;
|
||||
const formatter = () => props.formatter ?? ((v: number) => String(Math.round(v)));
|
||||
|
||||
createEffect(() => {
|
||||
const target = props.value;
|
||||
const dur = duration();
|
||||
const dly = delay();
|
||||
|
||||
setDisplayValue(0);
|
||||
|
||||
let delayTimeoutId: ReturnType<typeof setTimeout> | undefined;
|
||||
let animationTimeoutId: ReturnType<typeof setTimeout> | undefined;
|
||||
let startTime: number | undefined;
|
||||
let cancelled = false;
|
||||
|
||||
const animate = () => {
|
||||
if (cancelled) return;
|
||||
|
||||
const now = Date.now();
|
||||
if (!startTime) startTime = now;
|
||||
const elapsed = now - startTime;
|
||||
const progress = Math.min(elapsed / dur, 1);
|
||||
const eased = 1 - Math.pow(1 - progress, 4);
|
||||
|
||||
setDisplayValue(eased * target);
|
||||
|
||||
if (progress < 1) {
|
||||
animationTimeoutId = setTimeout(animate, 16);
|
||||
}
|
||||
};
|
||||
|
||||
if (dly > 0) {
|
||||
delayTimeoutId = setTimeout(() => {
|
||||
animationTimeoutId = setTimeout(animate, 16);
|
||||
}, dly);
|
||||
} else {
|
||||
animationTimeoutId = setTimeout(animate, 16);
|
||||
}
|
||||
|
||||
onCleanup(() => {
|
||||
cancelled = true;
|
||||
if (delayTimeoutId) clearTimeout(delayTimeoutId);
|
||||
if (animationTimeoutId) clearTimeout(animationTimeoutId);
|
||||
});
|
||||
});
|
||||
|
||||
return (
|
||||
<text fg={color()}>
|
||||
{props.prefix ?? ''}
|
||||
{formatter()(displayValue())}
|
||||
{props.suffix ?? ''}
|
||||
</text>
|
||||
);
|
||||
}
|
||||
|
||||
interface BlinkingTextProps {
|
||||
text: string;
|
||||
interval?: number;
|
||||
color?: string;
|
||||
blinkColor?: string;
|
||||
}
|
||||
|
||||
export function BlinkingText(props: BlinkingTextProps) {
|
||||
const [visible, setVisible] = createSignal(true);
|
||||
const interval = () => props.interval ?? 500;
|
||||
const color = () => props.color ?? terminalColors.text;
|
||||
const blinkColor = () => props.blinkColor ?? terminalColors.textMuted;
|
||||
|
||||
createEffect(() => {
|
||||
const timer = setInterval(() => {
|
||||
setVisible((v) => !v);
|
||||
}, interval());
|
||||
|
||||
onCleanup(() => clearInterval(timer));
|
||||
});
|
||||
|
||||
return <text fg={visible() ? color() : blinkColor()}>{props.text}</text>;
|
||||
}
|
||||
|
||||
interface PulsingTextProps {
|
||||
text: string;
|
||||
color?: string;
|
||||
pulseColor?: string;
|
||||
interval?: number;
|
||||
}
|
||||
|
||||
export function PulsingText(props: PulsingTextProps) {
|
||||
const [phase, setPhase] = createSignal(0);
|
||||
const interval = () => props.interval ?? 100;
|
||||
const color = () => props.color ?? terminalColors.accent;
|
||||
const pulseColor = () => props.pulseColor ?? terminalColors.text;
|
||||
|
||||
createEffect(() => {
|
||||
const timer = setInterval(() => {
|
||||
setPhase((p) => (p + 1) % 20);
|
||||
}, interval());
|
||||
|
||||
onCleanup(() => clearInterval(timer));
|
||||
});
|
||||
|
||||
const currentColor = () => {
|
||||
const p = phase();
|
||||
if (p < 10) return color();
|
||||
return pulseColor();
|
||||
};
|
||||
|
||||
return <text fg={currentColor()}>{props.text}</text>;
|
||||
}
|
||||
@@ -0,0 +1,55 @@
|
||||
import { type Screen } from '../state/types.js';
|
||||
import { terminalColors } from '../theme/colors.js';
|
||||
import { symbols } from '../theme/symbols.js';
|
||||
import { getVersion } from '../utils/helpers.js';
|
||||
|
||||
interface BottomStatusBarProps {
|
||||
currentScreen: Screen;
|
||||
}
|
||||
|
||||
const SCREEN_LABELS: Record<Screen, string> = {
|
||||
home: 'Home',
|
||||
browse: 'Browse',
|
||||
marketplace: 'Marketplace',
|
||||
installed: 'Installed',
|
||||
settings: 'Settings',
|
||||
recommend: 'Recommend',
|
||||
translate: 'Translate',
|
||||
context: 'Context',
|
||||
memory: 'Memory',
|
||||
team: 'Team',
|
||||
plugins: 'Plugins',
|
||||
methodology: 'Methodology',
|
||||
plan: 'Plan',
|
||||
workflow: 'Workflow',
|
||||
execute: 'Execute',
|
||||
history: 'History',
|
||||
sync: 'Sync',
|
||||
help: 'Help',
|
||||
mesh: 'Mesh',
|
||||
message: 'Message',
|
||||
};
|
||||
|
||||
export function BottomStatusBar(props: BottomStatusBarProps) {
|
||||
const version = getVersion();
|
||||
|
||||
return (
|
||||
<box
|
||||
flexDirection="row"
|
||||
height={1}
|
||||
borderTop
|
||||
borderColor={terminalColors.border}
|
||||
paddingX={1}
|
||||
>
|
||||
<text fg={terminalColors.accent}>
|
||||
<b>{symbols.brandIcon} skillkit</b> v{version}
|
||||
</text>
|
||||
<text fg={terminalColors.border}> {symbols.verticalLine} </text>
|
||||
<text fg={terminalColors.text}>
|
||||
<b>{SCREEN_LABELS[props.currentScreen]}</b>
|
||||
</text>
|
||||
<text fg={terminalColors.border}> {symbols.verticalLine} </text>
|
||||
<text fg={terminalColors.textMuted}>/ cmd h home m market q quit</text>
|
||||
</box>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,179 @@
|
||||
/**
|
||||
* Breadcrumb Component
|
||||
* Clickable breadcrumb navigation
|
||||
*/
|
||||
|
||||
import { For, Show } from 'solid-js';
|
||||
import { terminalColors } from '../theme/colors.js';
|
||||
|
||||
export interface BreadcrumbItem {
|
||||
id: string;
|
||||
label: string;
|
||||
icon?: string;
|
||||
}
|
||||
|
||||
interface BreadcrumbProps {
|
||||
items: BreadcrumbItem[];
|
||||
separator?: string;
|
||||
hoveredId?: string | null;
|
||||
onNavigate?: (id: string) => void;
|
||||
}
|
||||
|
||||
export function Breadcrumb(props: BreadcrumbProps) {
|
||||
const separator = () => props.separator ?? ' / ';
|
||||
|
||||
const handleClick = (id: string) => {
|
||||
props.onNavigate?.(id);
|
||||
};
|
||||
|
||||
return (
|
||||
<box flexDirection="row">
|
||||
<For each={props.items}>
|
||||
{(item, index) => {
|
||||
const isLast = () => index() === props.items.length - 1;
|
||||
const isHovered = () => item.id === props.hoveredId;
|
||||
|
||||
const fg = () => {
|
||||
if (isLast()) return terminalColors.text;
|
||||
if (isHovered()) return terminalColors.accent;
|
||||
return terminalColors.textMuted;
|
||||
};
|
||||
|
||||
return (
|
||||
<>
|
||||
<box
|
||||
flexDirection="row"
|
||||
onClick={() => handleClick(item.id)}
|
||||
>
|
||||
<Show when={item.icon}>
|
||||
<text fg={fg()}>{item.icon} </text>
|
||||
</Show>
|
||||
<text fg={fg()}>
|
||||
{isLast() ? <b>{item.label}</b> : item.label}
|
||||
</text>
|
||||
</box>
|
||||
<Show when={!isLast()}>
|
||||
<text fg={terminalColors.textMuted}>{separator()}</text>
|
||||
</Show>
|
||||
</>
|
||||
);
|
||||
}}
|
||||
</For>
|
||||
</box>
|
||||
);
|
||||
}
|
||||
|
||||
interface PathBreadcrumbProps {
|
||||
path: string;
|
||||
separator?: string;
|
||||
maxSegments?: number;
|
||||
hoveredSegment?: number | null;
|
||||
onNavigate?: (path: string, segmentIndex: number) => void;
|
||||
}
|
||||
|
||||
export function PathBreadcrumb(props: PathBreadcrumbProps) {
|
||||
const separator = () => props.separator ?? '/';
|
||||
const maxSegments = () => props.maxSegments ?? 5;
|
||||
|
||||
const segments = () => {
|
||||
const parts = props.path.split('/').filter(Boolean);
|
||||
if (parts.length <= maxSegments()) {
|
||||
return parts;
|
||||
}
|
||||
return ['...', ...parts.slice(-(maxSegments() - 1))];
|
||||
};
|
||||
|
||||
const getPathAtIndex = (index: number): string => {
|
||||
const parts = props.path.split('/').filter(Boolean);
|
||||
const segs = segments();
|
||||
let actualIndex: number;
|
||||
|
||||
if (segs[0] === '...') {
|
||||
const offset = parts.length - (segs.length - 1);
|
||||
actualIndex = offset + index - 1;
|
||||
} else {
|
||||
actualIndex = index;
|
||||
}
|
||||
|
||||
return '/' + parts.slice(0, actualIndex + 1).join('/');
|
||||
};
|
||||
|
||||
const handleClick = (segment: string, index: number) => {
|
||||
if (segment === '...') return;
|
||||
props.onNavigate?.(getPathAtIndex(index), index);
|
||||
};
|
||||
|
||||
return (
|
||||
<box flexDirection="row">
|
||||
<text fg={terminalColors.textMuted}>{separator()}</text>
|
||||
<For each={segments()}>
|
||||
{(segment, index) => {
|
||||
const isLast = () => index() === segments().length - 1;
|
||||
const isHovered = () => index() === props.hoveredSegment;
|
||||
const isEllipsis = () => segment === '...';
|
||||
|
||||
const fg = () => {
|
||||
if (isEllipsis()) return terminalColors.textMuted;
|
||||
if (isLast()) return terminalColors.text;
|
||||
if (isHovered()) return terminalColors.accent;
|
||||
return terminalColors.textMuted;
|
||||
};
|
||||
|
||||
return (
|
||||
<>
|
||||
<text
|
||||
fg={fg()}
|
||||
onClick={() => handleClick(segment, index())}
|
||||
>
|
||||
{isLast() ? <b>{segment}</b> : segment}
|
||||
</text>
|
||||
<Show when={!isLast()}>
|
||||
<text fg={terminalColors.textMuted}>{separator()}</text>
|
||||
</Show>
|
||||
</>
|
||||
);
|
||||
}}
|
||||
</For>
|
||||
</box>
|
||||
);
|
||||
}
|
||||
|
||||
interface NavigationTrailProps {
|
||||
items: Array<{ screen: string; label: string }>;
|
||||
currentIndex: number;
|
||||
hoveredIndex?: number | null;
|
||||
}
|
||||
|
||||
export function NavigationTrail(props: NavigationTrailProps) {
|
||||
return (
|
||||
<box flexDirection="row">
|
||||
<For each={props.items}>
|
||||
{(item, index) => {
|
||||
const isCurrent = () => index() === props.currentIndex;
|
||||
const isPast = () => index() < props.currentIndex;
|
||||
const isHovered = () => index() === props.hoveredIndex;
|
||||
|
||||
const fg = () => {
|
||||
if (isCurrent()) return terminalColors.accent;
|
||||
if (isHovered()) return terminalColors.text;
|
||||
if (isPast()) return terminalColors.textSecondary;
|
||||
return terminalColors.textMuted;
|
||||
};
|
||||
|
||||
const indicator = () => {
|
||||
if (isCurrent()) return '●';
|
||||
if (isPast()) return '○';
|
||||
return '○';
|
||||
};
|
||||
|
||||
return (
|
||||
<box flexDirection="row" marginRight={2}>
|
||||
<text fg={fg()}>{indicator()} </text>
|
||||
<text fg={fg()}>{item.label}</text>
|
||||
</box>
|
||||
);
|
||||
}}
|
||||
</For>
|
||||
</box>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,197 @@
|
||||
/**
|
||||
* Button Component
|
||||
* Clickable button with hover/active states
|
||||
*/
|
||||
|
||||
import { Show } from 'solid-js';
|
||||
import { terminalColors } from '../theme/colors.js';
|
||||
|
||||
export type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
|
||||
export type ButtonSize = 'sm' | 'md' | 'lg';
|
||||
|
||||
interface ButtonProps {
|
||||
label: string;
|
||||
shortcut?: string;
|
||||
icon?: string;
|
||||
variant?: ButtonVariant;
|
||||
size?: ButtonSize;
|
||||
disabled?: boolean;
|
||||
focused?: boolean;
|
||||
pressed?: boolean;
|
||||
hovered?: boolean;
|
||||
onClick?: () => void;
|
||||
}
|
||||
|
||||
const VARIANT_COLORS: Record<
|
||||
ButtonVariant,
|
||||
{ fg: string; bg: string; border: string; hoverFg: string }
|
||||
> = {
|
||||
primary: {
|
||||
fg: terminalColors.text,
|
||||
bg: terminalColors.accent,
|
||||
border: terminalColors.accent,
|
||||
hoverFg: terminalColors.accent,
|
||||
},
|
||||
secondary: {
|
||||
fg: terminalColors.text,
|
||||
bg: terminalColors.surface,
|
||||
border: terminalColors.border,
|
||||
hoverFg: terminalColors.text,
|
||||
},
|
||||
ghost: {
|
||||
fg: terminalColors.textSecondary,
|
||||
bg: 'transparent',
|
||||
border: 'transparent',
|
||||
hoverFg: terminalColors.text,
|
||||
},
|
||||
danger: {
|
||||
fg: terminalColors.text,
|
||||
bg: terminalColors.error,
|
||||
border: terminalColors.error,
|
||||
hoverFg: terminalColors.error,
|
||||
},
|
||||
};
|
||||
|
||||
export function Button(props: ButtonProps) {
|
||||
const variant = () => props.variant ?? 'secondary';
|
||||
const size = () => props.size ?? 'md';
|
||||
const disabled = () => props.disabled ?? false;
|
||||
const focused = () => props.focused ?? false;
|
||||
const pressed = () => props.pressed ?? false;
|
||||
const hovered = () => props.hovered ?? false;
|
||||
|
||||
const colors = () => VARIANT_COLORS[variant()];
|
||||
|
||||
const fg = () => {
|
||||
if (disabled()) return terminalColors.textMuted;
|
||||
if (pressed()) return colors().hoverFg;
|
||||
if (hovered() || focused()) return colors().hoverFg;
|
||||
return colors().fg;
|
||||
};
|
||||
|
||||
const borderColor = () => {
|
||||
if (disabled()) return terminalColors.textMuted;
|
||||
if (focused()) return terminalColors.accent;
|
||||
return colors().border;
|
||||
};
|
||||
|
||||
const paddingX = () => {
|
||||
switch (size()) {
|
||||
case 'sm':
|
||||
return 1;
|
||||
case 'lg':
|
||||
return 3;
|
||||
default:
|
||||
return 2;
|
||||
}
|
||||
};
|
||||
|
||||
const brackets = () => {
|
||||
if (variant() === 'ghost') return { left: '', right: '' };
|
||||
if (pressed()) return { left: '▸', right: '◂' };
|
||||
return { left: '[', right: ']' };
|
||||
};
|
||||
|
||||
const padding = ' '.repeat(paddingX());
|
||||
|
||||
const handleClick = () => {
|
||||
if (!disabled() && props.onClick) {
|
||||
props.onClick();
|
||||
}
|
||||
};
|
||||
|
||||
return (
|
||||
<box flexDirection="row" onClick={handleClick}>
|
||||
<text fg={borderColor()}>{brackets().left}</text>
|
||||
<text fg={fg()}>{padding}</text>
|
||||
<Show when={props.icon}>
|
||||
<text fg={fg()}>{props.icon} </text>
|
||||
</Show>
|
||||
<text fg={fg()}>{props.label}</text>
|
||||
<Show when={props.shortcut}>
|
||||
<text fg={terminalColors.textMuted}> ({props.shortcut})</text>
|
||||
</Show>
|
||||
<text fg={fg()}>{padding}</text>
|
||||
<text fg={borderColor()}>{brackets().right}</text>
|
||||
</box>
|
||||
);
|
||||
}
|
||||
|
||||
interface ButtonGroupProps {
|
||||
buttons: Array<{
|
||||
id: string;
|
||||
label: string;
|
||||
shortcut?: string;
|
||||
icon?: string;
|
||||
variant?: ButtonVariant;
|
||||
disabled?: boolean;
|
||||
onClick?: () => void;
|
||||
}>;
|
||||
selectedId?: string;
|
||||
focusedId?: string;
|
||||
direction?: 'horizontal' | 'vertical';
|
||||
gap?: number;
|
||||
}
|
||||
|
||||
export function ButtonGroup(props: ButtonGroupProps) {
|
||||
const direction = () => props.direction ?? 'horizontal';
|
||||
const gap = () => props.gap ?? 2;
|
||||
|
||||
return (
|
||||
<box flexDirection={direction() === 'horizontal' ? 'row' : 'column'}>
|
||||
{props.buttons.map((btn, index) => (
|
||||
<box
|
||||
marginRight={direction() === 'horizontal' && index < props.buttons.length - 1 ? gap() : 0}
|
||||
marginBottom={direction() === 'vertical' && index < props.buttons.length - 1 ? gap() : 0}
|
||||
>
|
||||
<Button
|
||||
label={btn.label}
|
||||
shortcut={btn.shortcut}
|
||||
icon={btn.icon}
|
||||
variant={btn.variant}
|
||||
disabled={btn.disabled}
|
||||
focused={btn.id === props.focusedId}
|
||||
hovered={btn.id === props.selectedId}
|
||||
onClick={btn.onClick}
|
||||
/>
|
||||
</box>
|
||||
))}
|
||||
</box>
|
||||
);
|
||||
}
|
||||
|
||||
interface IconButtonProps {
|
||||
icon: string;
|
||||
label?: string;
|
||||
disabled?: boolean;
|
||||
focused?: boolean;
|
||||
hovered?: boolean;
|
||||
onClick?: () => void;
|
||||
}
|
||||
|
||||
export function IconButton(props: IconButtonProps) {
|
||||
const disabled = () => props.disabled ?? false;
|
||||
const focused = () => props.focused ?? false;
|
||||
const hovered = () => props.hovered ?? false;
|
||||
|
||||
const fg = () => {
|
||||
if (disabled()) return terminalColors.textMuted;
|
||||
if (focused() || hovered()) return terminalColors.accent;
|
||||
return terminalColors.textSecondary;
|
||||
};
|
||||
|
||||
const handleClick = () => {
|
||||
if (!disabled() && props.onClick) {
|
||||
props.onClick();
|
||||
}
|
||||
};
|
||||
|
||||
return (
|
||||
<box flexDirection="row" onClick={handleClick}>
|
||||
<text fg={fg()}>{props.icon}</text>
|
||||
<Show when={props.label}>
|
||||
<text fg={fg()}> {props.label}</text>
|
||||
</Show>
|
||||
</box>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,196 @@
|
||||
/**
|
||||
* Clickable Component
|
||||
* Wrapper to make any element clickable with hover effects
|
||||
*/
|
||||
|
||||
import { type JSX, Show } from 'solid-js';
|
||||
import { terminalColors } from '../theme/colors.js';
|
||||
|
||||
interface ClickableProps {
|
||||
children: JSX.Element;
|
||||
onClick?: () => void;
|
||||
onDoubleClick?: () => void;
|
||||
onRightClick?: () => void;
|
||||
disabled?: boolean;
|
||||
hovered?: boolean;
|
||||
pressed?: boolean;
|
||||
focusable?: boolean;
|
||||
focused?: boolean;
|
||||
cursor?: string;
|
||||
hoverEffect?: 'highlight' | 'underline' | 'pointer' | 'none';
|
||||
}
|
||||
|
||||
export function Clickable(props: ClickableProps) {
|
||||
const disabled = () => props.disabled ?? false;
|
||||
const hovered = () => props.hovered ?? false;
|
||||
const focused = () => props.focused ?? false;
|
||||
const hoverEffect = () => props.hoverEffect ?? 'highlight';
|
||||
|
||||
const showHighlight = () => {
|
||||
if (disabled()) return false;
|
||||
return hovered() || focused();
|
||||
};
|
||||
|
||||
const cursor = () => {
|
||||
if (disabled()) return '';
|
||||
if (hovered()) return props.cursor ?? '▸';
|
||||
return '';
|
||||
};
|
||||
|
||||
const handleClick = () => {
|
||||
if (!disabled() && props.onClick) {
|
||||
props.onClick();
|
||||
}
|
||||
};
|
||||
|
||||
const handleDoubleClick = () => {
|
||||
if (!disabled() && props.onDoubleClick) {
|
||||
props.onDoubleClick();
|
||||
}
|
||||
};
|
||||
|
||||
const handleRightClick = () => {
|
||||
if (!disabled() && props.onRightClick) {
|
||||
props.onRightClick();
|
||||
}
|
||||
};
|
||||
|
||||
const renderContent = () => {
|
||||
if (hoverEffect() === 'underline' && showHighlight()) {
|
||||
return <text>{props.children}</text>;
|
||||
}
|
||||
return props.children;
|
||||
};
|
||||
|
||||
return (
|
||||
<box
|
||||
flexDirection="row"
|
||||
onClick={handleClick}
|
||||
onDoubleClick={handleDoubleClick}
|
||||
onContextMenu={handleRightClick}
|
||||
>
|
||||
<Show when={hoverEffect() === 'pointer' && showHighlight()}>
|
||||
<text fg={terminalColors.accent}>{cursor()} </text>
|
||||
</Show>
|
||||
<box
|
||||
fg={hoverEffect() === 'highlight' && showHighlight() ? terminalColors.accent : undefined}
|
||||
>
|
||||
{renderContent()}
|
||||
</box>
|
||||
</box>
|
||||
);
|
||||
}
|
||||
|
||||
interface ClickableTextProps {
|
||||
children: string;
|
||||
onClick?: () => void;
|
||||
disabled?: boolean;
|
||||
hovered?: boolean;
|
||||
color?: string;
|
||||
hoverColor?: string;
|
||||
underlineOnHover?: boolean;
|
||||
}
|
||||
|
||||
export function ClickableText(props: ClickableTextProps) {
|
||||
const disabled = () => props.disabled ?? false;
|
||||
const hovered = () => props.hovered ?? false;
|
||||
const underlineOnHover = () => props.underlineOnHover ?? false;
|
||||
|
||||
const color = () => {
|
||||
if (disabled()) return terminalColors.textMuted;
|
||||
if (hovered()) return props.hoverColor ?? terminalColors.accent;
|
||||
return props.color ?? terminalColors.text;
|
||||
};
|
||||
|
||||
const handleClick = () => {
|
||||
if (!disabled() && props.onClick) {
|
||||
props.onClick();
|
||||
}
|
||||
};
|
||||
|
||||
return (
|
||||
<text fg={color()} onClick={handleClick}>
|
||||
{underlineOnHover() && hovered() ? (
|
||||
<u>{props.children}</u>
|
||||
) : (
|
||||
props.children
|
||||
)}
|
||||
</text>
|
||||
);
|
||||
}
|
||||
|
||||
interface ClickableRowProps {
|
||||
children: JSX.Element;
|
||||
selected?: boolean;
|
||||
hovered?: boolean;
|
||||
disabled?: boolean;
|
||||
showIndicator?: boolean;
|
||||
indicatorChar?: string;
|
||||
onClick?: () => void;
|
||||
}
|
||||
|
||||
export function ClickableRow(props: ClickableRowProps) {
|
||||
const selected = () => props.selected ?? false;
|
||||
const hovered = () => props.hovered ?? false;
|
||||
const disabled = () => props.disabled ?? false;
|
||||
const showIndicator = () => props.showIndicator ?? true;
|
||||
const indicatorChar = () => props.indicatorChar ?? '▸';
|
||||
|
||||
const indicator = () => {
|
||||
if (!showIndicator()) return ' ';
|
||||
if (selected()) return `${indicatorChar()} `;
|
||||
if (hovered()) return '▹ ';
|
||||
return ' ';
|
||||
};
|
||||
|
||||
const fg = () => {
|
||||
if (disabled()) return terminalColors.textMuted;
|
||||
if (selected()) return terminalColors.accent;
|
||||
if (hovered()) return terminalColors.text;
|
||||
return terminalColors.textSecondary;
|
||||
};
|
||||
|
||||
const handleClick = () => {
|
||||
if (!disabled() && props.onClick) {
|
||||
props.onClick();
|
||||
}
|
||||
};
|
||||
|
||||
return (
|
||||
<box flexDirection="row" onClick={handleClick}>
|
||||
<text fg={fg()}>{indicator()}</text>
|
||||
{props.children}
|
||||
</box>
|
||||
);
|
||||
}
|
||||
|
||||
interface InteractiveAreaProps {
|
||||
children: JSX.Element;
|
||||
x?: number;
|
||||
y?: number;
|
||||
width?: number;
|
||||
height?: number;
|
||||
onMouseOver?: () => void;
|
||||
onMouseOut?: () => void;
|
||||
onClick?: () => void;
|
||||
onMouseDown?: () => void;
|
||||
onMouseUp?: () => void;
|
||||
}
|
||||
|
||||
export function InteractiveArea(props: InteractiveAreaProps) {
|
||||
return (
|
||||
<box
|
||||
flexDirection="column"
|
||||
width={props.width}
|
||||
height={props.height}
|
||||
style={{ left: props.x, top: props.y }}
|
||||
onMouseEnter={props.onMouseOver}
|
||||
onMouseLeave={props.onMouseOut}
|
||||
onClick={props.onClick}
|
||||
onMouseDown={props.onMouseDown}
|
||||
onMouseUp={props.onMouseUp}
|
||||
>
|
||||
{props.children}
|
||||
</box>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,194 @@
|
||||
/**
|
||||
* CodeBlock Component
|
||||
* Basic syntax highlighting for code display
|
||||
*/
|
||||
|
||||
import { For, Show } from 'solid-js';
|
||||
import { terminalColors } from '../theme/colors.js';
|
||||
|
||||
interface CodeBlockProps {
|
||||
code: string;
|
||||
language?: string;
|
||||
showLineNumbers?: boolean;
|
||||
maxLines?: number;
|
||||
highlightLines?: number[];
|
||||
title?: string;
|
||||
}
|
||||
|
||||
const KEYWORDS = new Set([
|
||||
'const',
|
||||
'let',
|
||||
'var',
|
||||
'function',
|
||||
'return',
|
||||
'if',
|
||||
'else',
|
||||
'for',
|
||||
'while',
|
||||
'import',
|
||||
'export',
|
||||
'from',
|
||||
'class',
|
||||
'extends',
|
||||
'async',
|
||||
'await',
|
||||
'try',
|
||||
'catch',
|
||||
'throw',
|
||||
'new',
|
||||
'this',
|
||||
'true',
|
||||
'false',
|
||||
'null',
|
||||
'undefined',
|
||||
'type',
|
||||
'interface',
|
||||
]);
|
||||
|
||||
function tokenizeLine(line: string): Array<{ type: string; value: string }> {
|
||||
const tokens: Array<{ type: string; value: string }> = [];
|
||||
let remaining = line;
|
||||
|
||||
while (remaining.length > 0) {
|
||||
if (remaining.startsWith('//')) {
|
||||
tokens.push({ type: 'comment', value: remaining });
|
||||
break;
|
||||
}
|
||||
|
||||
const stringMatch = remaining.match(/^(['"`])(?:\\.|[^\\])*?\1/);
|
||||
if (stringMatch) {
|
||||
tokens.push({ type: 'string', value: stringMatch[0] });
|
||||
remaining = remaining.slice(stringMatch[0].length);
|
||||
continue;
|
||||
}
|
||||
|
||||
const numberMatch = remaining.match(/^\d+\.?\d*/);
|
||||
if (numberMatch) {
|
||||
tokens.push({ type: 'number', value: numberMatch[0] });
|
||||
remaining = remaining.slice(numberMatch[0].length);
|
||||
continue;
|
||||
}
|
||||
|
||||
const wordMatch = remaining.match(/^[a-zA-Z_$][a-zA-Z0-9_$]*/);
|
||||
if (wordMatch) {
|
||||
const word = wordMatch[0];
|
||||
const type = KEYWORDS.has(word) ? 'keyword' : 'identifier';
|
||||
tokens.push({ type, value: word });
|
||||
remaining = remaining.slice(word.length);
|
||||
continue;
|
||||
}
|
||||
|
||||
const spaceMatch = remaining.match(/^\s+/);
|
||||
if (spaceMatch) {
|
||||
tokens.push({ type: 'space', value: spaceMatch[0] });
|
||||
remaining = remaining.slice(spaceMatch[0].length);
|
||||
continue;
|
||||
}
|
||||
|
||||
tokens.push({ type: 'punctuation', value: remaining[0] });
|
||||
remaining = remaining.slice(1);
|
||||
}
|
||||
|
||||
return tokens;
|
||||
}
|
||||
|
||||
function getTokenColor(type: string): string {
|
||||
switch (type) {
|
||||
case 'keyword':
|
||||
return terminalColors.accent;
|
||||
case 'string':
|
||||
return terminalColors.warning;
|
||||
case 'number':
|
||||
return terminalColors.info;
|
||||
case 'comment':
|
||||
return terminalColors.textMuted;
|
||||
default:
|
||||
return terminalColors.text;
|
||||
}
|
||||
}
|
||||
|
||||
export function CodeBlock(props: CodeBlockProps) {
|
||||
const showLineNumbers = () => props.showLineNumbers ?? true;
|
||||
const highlightLines = () => new Set(props.highlightLines ?? []);
|
||||
|
||||
const lines = () => {
|
||||
const allLines = props.code.split('\n');
|
||||
if (props.maxLines && allLines.length > props.maxLines) {
|
||||
return allLines.slice(0, props.maxLines);
|
||||
}
|
||||
return allLines;
|
||||
};
|
||||
|
||||
const lineNumberWidth = () => String(lines().length).length + 1;
|
||||
|
||||
const isTruncated = () => {
|
||||
const allLines = props.code.split('\n');
|
||||
return props.maxLines !== undefined && allLines.length > props.maxLines;
|
||||
};
|
||||
|
||||
return (
|
||||
<box flexDirection="column">
|
||||
<Show when={props.title}>
|
||||
<box marginBottom={1}>
|
||||
<text fg={terminalColors.textMuted}>
|
||||
{props.title}
|
||||
</text>
|
||||
</box>
|
||||
</Show>
|
||||
|
||||
<box
|
||||
flexDirection="column"
|
||||
borderStyle="round"
|
||||
borderColor={terminalColors.border}
|
||||
paddingX={1}
|
||||
>
|
||||
<For each={lines()}>
|
||||
{(line, index) => {
|
||||
const lineNum = index() + 1;
|
||||
const isHighlighted = highlightLines().has(lineNum);
|
||||
const tokens = tokenizeLine(line);
|
||||
|
||||
return (
|
||||
<box flexDirection="row">
|
||||
<Show when={showLineNumbers()}>
|
||||
<text
|
||||
fg={isHighlighted ? terminalColors.accent : terminalColors.textMuted}
|
||||
width={lineNumberWidth()}
|
||||
>
|
||||
{isHighlighted ? '▸' : ' '}
|
||||
{String(lineNum).padStart(lineNumberWidth() - 1, ' ')}{' '}
|
||||
</text>
|
||||
</Show>
|
||||
<For each={tokens}>
|
||||
{(token) => (
|
||||
<text fg={isHighlighted ? terminalColors.accent : getTokenColor(token.type)}>
|
||||
{token.value}
|
||||
</text>
|
||||
)}
|
||||
</For>
|
||||
</box>
|
||||
);
|
||||
}}
|
||||
</For>
|
||||
|
||||
<Show when={isTruncated()}>
|
||||
<text fg={terminalColors.textMuted}>
|
||||
... {props.code.split('\n').length - (props.maxLines ?? 0)} more lines
|
||||
</text>
|
||||
</Show>
|
||||
</box>
|
||||
</box>
|
||||
);
|
||||
}
|
||||
|
||||
interface InlineCodeProps {
|
||||
children: string;
|
||||
}
|
||||
|
||||
export function InlineCode(props: InlineCodeProps) {
|
||||
return (
|
||||
<text fg={terminalColors.accent}>
|
||||
`{props.children}`
|
||||
</text>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,135 @@
|
||||
/**
|
||||
* DetailPane Component
|
||||
* Right-side detail panel with animated slide-in
|
||||
*/
|
||||
|
||||
import { Show, For, createSignal, createEffect, onCleanup, type JSX } from 'solid-js';
|
||||
import { terminalColors } from '../theme/colors.js';
|
||||
|
||||
export interface DetailField {
|
||||
label: string;
|
||||
value: string | string[];
|
||||
color?: string;
|
||||
}
|
||||
|
||||
interface DetailPaneProps {
|
||||
title: string;
|
||||
subtitle?: string;
|
||||
icon?: string;
|
||||
fields?: DetailField[];
|
||||
content?: string;
|
||||
actions?: Array<{ key: string; label: string }>;
|
||||
width?: number;
|
||||
visible?: boolean;
|
||||
onClose?: () => void;
|
||||
children?: JSX.Element;
|
||||
}
|
||||
|
||||
export function DetailPane(props: DetailPaneProps) {
|
||||
const [slideProgress, setSlideProgress] = createSignal(0);
|
||||
const width = () => props.width ?? 30;
|
||||
const visible = () => props.visible ?? true;
|
||||
|
||||
createEffect(() => {
|
||||
if (visible()) {
|
||||
let frame = 0;
|
||||
let timeoutId: ReturnType<typeof setTimeout>;
|
||||
const animate = () => {
|
||||
frame++;
|
||||
const progress = Math.min(frame / 10, 1);
|
||||
setSlideProgress(progress);
|
||||
if (progress < 1) {
|
||||
timeoutId = setTimeout(animate, 16);
|
||||
}
|
||||
};
|
||||
timeoutId = setTimeout(animate, 16);
|
||||
onCleanup(() => clearTimeout(timeoutId));
|
||||
} else {
|
||||
setSlideProgress(0);
|
||||
}
|
||||
});
|
||||
|
||||
const effectiveWidth = () => Math.round(width() * slideProgress());
|
||||
|
||||
return (
|
||||
<Show when={visible() && slideProgress() > 0}>
|
||||
<box
|
||||
flexDirection="column"
|
||||
width={effectiveWidth()}
|
||||
borderStyle="round"
|
||||
borderColor={terminalColors.border}
|
||||
paddingX={1}
|
||||
paddingY={1}
|
||||
>
|
||||
<box flexDirection="row" marginBottom={1}>
|
||||
<Show when={props.icon}>
|
||||
<text fg={terminalColors.accent}>{props.icon} </text>
|
||||
</Show>
|
||||
<text fg={terminalColors.text}>
|
||||
<b>{props.title}</b>
|
||||
</text>
|
||||
<Show when={props.onClose}>
|
||||
<box onClick={() => props.onClose?.()}>
|
||||
<text fg={terminalColors.textMuted}> [x]</text>
|
||||
</box>
|
||||
</Show>
|
||||
</box>
|
||||
|
||||
<Show when={props.subtitle}>
|
||||
<box marginBottom={1}>
|
||||
<text fg={terminalColors.textMuted}>{props.subtitle}</text>
|
||||
</box>
|
||||
</Show>
|
||||
|
||||
<Show when={props.fields && props.fields.length > 0}>
|
||||
<box flexDirection="column" marginBottom={1}>
|
||||
<For each={props.fields}>
|
||||
{(field) => (
|
||||
<box flexDirection="column" marginBottom={1}>
|
||||
<text fg={terminalColors.textMuted}>{field.label}</text>
|
||||
<Show
|
||||
when={Array.isArray(field.value)}
|
||||
fallback={
|
||||
<text fg={field.color || terminalColors.text}>
|
||||
{field.value as string}
|
||||
</text>
|
||||
}
|
||||
>
|
||||
<For each={field.value as string[]}>
|
||||
{(val) => (
|
||||
<text fg={field.color || terminalColors.text}>• {val}</text>
|
||||
)}
|
||||
</For>
|
||||
</Show>
|
||||
</box>
|
||||
)}
|
||||
</For>
|
||||
</box>
|
||||
</Show>
|
||||
|
||||
<Show when={props.content}>
|
||||
<box flexDirection="column" marginBottom={1}>
|
||||
<text fg={terminalColors.text}>{props.content}</text>
|
||||
</box>
|
||||
</Show>
|
||||
|
||||
<Show when={props.children}>
|
||||
<box flexDirection="column" marginBottom={1}>
|
||||
{props.children}
|
||||
</box>
|
||||
</Show>
|
||||
|
||||
<Show when={props.actions && props.actions.length > 0}>
|
||||
<text fg={terminalColors.textMuted}>─────</text>
|
||||
<For each={props.actions}>
|
||||
{(action) => (
|
||||
<text fg={terminalColors.textMuted}>
|
||||
<text fg={terminalColors.accent}>{action.key}</text> {action.label}
|
||||
</text>
|
||||
)}
|
||||
</For>
|
||||
</Show>
|
||||
</box>
|
||||
</Show>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,109 @@
|
||||
/**
|
||||
* EmptyState Component
|
||||
* Consistent "no data" display
|
||||
*/
|
||||
|
||||
import { Show } from 'solid-js';
|
||||
import { terminalColors } from '../theme/colors.js';
|
||||
|
||||
interface EmptyStateProps {
|
||||
icon?: string;
|
||||
title: string;
|
||||
description?: string;
|
||||
action?: {
|
||||
label: string;
|
||||
key?: string;
|
||||
};
|
||||
compact?: boolean;
|
||||
}
|
||||
|
||||
export function EmptyState(props: EmptyStateProps) {
|
||||
const compact = () => props.compact ?? false;
|
||||
|
||||
return (
|
||||
<box flexDirection="column" alignItems="center" paddingY={compact() ? 1 : 3}>
|
||||
<Show when={props.icon}>
|
||||
<box marginBottom={1}>
|
||||
<text fg={terminalColors.textMuted}>
|
||||
{props.icon}
|
||||
</text>
|
||||
</box>
|
||||
</Show>
|
||||
|
||||
<box marginBottom={1}>
|
||||
<text fg={terminalColors.textSecondary}>
|
||||
{props.title}
|
||||
</text>
|
||||
</box>
|
||||
|
||||
<Show when={props.description}>
|
||||
<text fg={terminalColors.textMuted}>{props.description}</text>
|
||||
</Show>
|
||||
|
||||
<Show when={props.action}>
|
||||
<box marginTop={1}>
|
||||
<text fg={terminalColors.textMuted}>
|
||||
<Show when={props.action!.key}>
|
||||
<text fg={terminalColors.accent}>{props.action!.key}</text>{' '}
|
||||
</Show>
|
||||
{props.action!.label}
|
||||
</text>
|
||||
</box>
|
||||
</Show>
|
||||
</box>
|
||||
);
|
||||
}
|
||||
|
||||
interface LoadingStateProps {
|
||||
message?: string;
|
||||
compact?: boolean;
|
||||
}
|
||||
|
||||
export function LoadingState(props: LoadingStateProps) {
|
||||
const compact = () => props.compact ?? false;
|
||||
const message = () => props.message ?? 'Loading...';
|
||||
|
||||
return (
|
||||
<box flexDirection="column" alignItems="center" paddingY={compact() ? 1 : 3}>
|
||||
<text fg={terminalColors.accent}>⟳ {message()}</text>
|
||||
</box>
|
||||
);
|
||||
}
|
||||
|
||||
interface ErrorStateProps {
|
||||
title?: string;
|
||||
message: string;
|
||||
action?: {
|
||||
label: string;
|
||||
key?: string;
|
||||
};
|
||||
compact?: boolean;
|
||||
}
|
||||
|
||||
export function ErrorState(props: ErrorStateProps) {
|
||||
const compact = () => props.compact ?? false;
|
||||
const title = () => props.title ?? 'Error';
|
||||
|
||||
return (
|
||||
<box flexDirection="column" alignItems="center" paddingY={compact() ? 1 : 3}>
|
||||
<box marginBottom={1}>
|
||||
<text fg={terminalColors.error}>
|
||||
✗ {title()}
|
||||
</text>
|
||||
</box>
|
||||
|
||||
<text fg={terminalColors.textMuted}>{props.message}</text>
|
||||
|
||||
<Show when={props.action}>
|
||||
<box marginTop={1}>
|
||||
<text fg={terminalColors.textMuted}>
|
||||
<Show when={props.action!.key}>
|
||||
<text fg={terminalColors.accent}>{props.action!.key}</text>{' '}
|
||||
</Show>
|
||||
{props.action!.label}
|
||||
</text>
|
||||
</box>
|
||||
</Show>
|
||||
</box>
|
||||
);
|
||||
}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user