Compare commits

..
Author SHA1 Message Date
Rohit Ghumare 553a918b69 fix: handle more relative path patterns in loadPlugin
- Use isAbsolute() for cross-platform absolute path detection
- Add check for paths containing '/' (excluding @scope packages)
- Simplify pattern to source.startsWith('.') for all dot-prefixed paths
- Now correctly handles: plugins/x.js, ../foo, ./bar, .hidden
2026-01-23 22:31:26 +00:00
Rohit Ghumare 380188cef1 fix: allow scoped npm names in isValidPluginName
Update isValidPluginName to allow scoped npm package names like @scope/name
while still preventing path traversal attacks. Uses the same regex pattern
as loader.ts validatePlugin for consistency.

Valid names: my-plugin, @scope/plugin-name
Invalid names: ../evil, .hidden, name\\path, @../evil/name
2026-01-23 22:27:37 +00:00
Rohit Ghumare dcf12f6826 fix: address PR review issues - round 5
CRITICAL fixes:
- plugin.ts: Add path traversal protection in uninstallPlugin with name validation
  and resolved path checks
- bundle.ts: Fix parseSkillContent to not drop first file when content starts
  with "--- file ---" header

MAJOR fixes:
- plugin.ts: Add isValidPluginName() helper and validate plugin.metadata.name
  before using in file paths
- plugin.ts: Preserve .mjs extension for single-file ESM plugins
- bundle.ts: Use cross-platform path containment checks with relative() and sep
  instead of hardcoded '/'
- loader.ts: Add support for .mjs files (index.mjs, plugin.mjs)

MINOR fixes:
- plugin.ts: Expand tilde (~) path BEFORE calling loadPlugin
- settings.ts: Use null instead of undefined in JSON output for --get so key
  is preserved
2026-01-23 22:21:03 +00:00
Rohit Ghumare 50e8a389de fix: address PR review issues - round 4
CRITICAL fixes:
- loader.ts: Wrap statSync in try/catch in loadPluginsFromDirectory to handle
  permission denied and broken symlinks
- bundle.ts: Block path traversal attacks via skill names in importBundle by
  validating skill names don't contain / \ or start with .

MAJOR fixes:
- bundle.ts: Use dirname() instead of join('..') for output directory calculation

MINOR fixes:
- plugin.ts: Expand tilde paths (~) before existsSync for proper file operations
- settings.ts: Show defaultTimeout and marketplaceSources in default output
- bundle.ts: Prevent duplicate skill names in bundle with early error
- bundle.ts: Handle single-file skills properly in detectAgents
2026-01-23 22:03:38 +00:00
Rohit Ghumare be06956fd4 fix: address PR review feedback (round 3)
- plugin.ts: Add '../' and '~' to isLocalPath detection, use
  loader-recognized names (index.js, plugin.json) for single-file copy
- plugin.ts: Remove unused 'basename' import
- settings.ts: Change defaultTimeout validation from < 0 to <= 0
- settings.ts: Use knownKeys whitelist for unknown key detection
- loader.ts: Wrap statSync in try/catch for scanDirectory
- loader.ts: Validate required fields (name, version) before pushing
- loader.ts: Update regex to allow scoped npm names (@scope/name)
- bundle.ts: Resolve targetDir to absolute path for path containment
- Plugins.tsx: Only ignore ENOENT errors, rethrow others
- Plugins.tsx: Load plugins in togglePlugin before enable/disable
2026-01-23 21:48:24 +00:00
Rohit Ghumare 402d179c06 fix: address PR review feedback (round 2)
- Security: Add path traversal protection in bundle import
- Fix Plugins.tsx to load plugins from directory before listing
- Fix plugin.ts to persist plugin files to disk on install/uninstall
- Fix Settings.tsx auto-detect vs universal display inconsistency
- Add null check for registry in team/manager.ts sync()
- Thread TeamConfig.auth through provider clone calls
- Fix GitLab CI rules vs only conflict (use rules instead of only)
- Make loadConfig() accept global parameter for --global flag
- Fix relative path detection in plugins/loader.ts (../plugins)
2026-01-23 21:28:50 +00:00
Rohit Ghumare f3467dd5d3 fix: address PR review comments from CodeRabbit and Devin
Plugin command fixes:
- Fix double-nested .skillkit path when using --global flag

Settings command fixes:
- Add defaultTimeout to help text for available keys
- Wrap const timeout in block scope for switch case
- Fix --set flag validation to require equals sign

Core package fixes:
- Remove .ts from supported plugin extensions (runtime imports fail)
- Store skill name instead of full path in bundle manifest
- Use ESM import for execSync instead of require()
- Replace custom YAML parser with yaml library for proper nested structure handling

TUI screen fixes:
- Guard against empty plugins array in navigation
- Fix empty object pattern in Settings.tsx
- Surface config load failures in Settings screen
- Add manager.load() before sync/import in Team screen
- Guard against empty skills array in Team navigation
- Clamp selection index after skills update

CI/CD command fixes:
- Properly handle skipped workflows (not reported as success)
- Show different final message when nothing was created
- Wrap readFileSync in try/catch for GitLab CI
2026-01-23 20:55:48 +00:00
Rohit Ghumare 08ab52971e fix: address PR review comments from Devin
- Fix skill-executor.ts: handle undefined agentToUse when strategy is 'cli'
  Previously, if strategy was 'cli' but no CLI agent was available, the
  code would fall through and call executeWithAgent with undefined agent,
  causing a runtime error.

- Fix cicd.ts: prevent GitLab CI config overwrite without --force
  Previously, if .gitlab-ci.yml existed but didn't contain 'skillkit',
  it would be overwritten without checking --force. Now it properly
  returns early with a helpful message, consistent with CircleCI behavior.
2026-01-23 20:26:47 +00:00
Rohit Ghumare 56c7d02103 feat: add team collaboration and plugin system
Team Collaboration (Phase 10):
- TeamManager for skill sharing with remote registries
- Skill bundles (create, export, import)
- Team CLI commands: init, share, import, list, sync, remove, bundle-*
- Team TUI screen with navigation key 'a'

Plugin System (Phase 11):
- PluginManager with lifecycle hooks
- Plugin loader (files, npm packages, directories)
- TranslatorPlugin for custom agent formats
- ProviderPlugin for custom skill sources
- CommandPlugin for custom CLI commands
- Plugin CLI commands: list, install, uninstall, enable, disable, info
- Plugins TUI screen with navigation key 'p'

Additional:
- CI/CD command for template generation
- Settings command improvements
- Updated CLAUDE.md with all 11 phases complete
- 359 tests passing
2026-01-23 20:17:59 +00:00
Rohit Ghumare b34177ca85 docs: rewrite READMEs with compelling value proposition
- Main README now leads with "One CLI. 17 AI Agents. Zero Lock-in."
- Clear problem/solution format showing SkillKit's value
- Feature comparison table (with vs without SkillKit)
- Organized command reference by category
- Updated all package READMEs with comprehensive docs:
  - @skillkit/core: Full API examples for all features
  - @skillkit/cli: Complete command reference
  - @skillkit/tui: Screen descriptions and keyboard shortcuts
  - @skillkit/agents: Agent adapter documentation
2026-01-23 18:24:07 +00:00
Rohit Ghumare 2fa62e6863 Merge branch 'feat/session-memory-system' 2026-01-23 18:18:57 +00:00
Rohit Ghumare 64b802a1e6 chore: release v1.4.0
New Features:
- Session Memory System: Cross-agent learning capture and sharing
- Skill Marketplace: Browse and install skills from curated repositories
- Skill Testing Framework: Test assertions and runner
- Workflow Orchestration: Multi-step skill compositions
- CI/CD Templates: GitHub Actions, GitLab CI, CircleCI support

Improvements:
- Enhanced TUI with marketplace browser
- Improved error-solution matching
- ReDoS protection for regex patterns
- Better input validation for CLI flags

All 346 tests passing.
2026-01-23 18:16:51 +00:00
Rohit Ghumare d3ffb79512 feat: add session memory system for cross-agent learning (#3)
* feat: add session memory system for cross-agent learning

Implements a lightweight, local-first memory system that works across
all 17 AI coding agents. Key features:

- YAML-based storage (no databases or external services)
- Three memory layers: Session, Project, and Global
- AI-powered compression of observations into learnings
- Cross-agent memory injection with relevance matching
- Progressive disclosure for token efficiency

Core modules:
- ObservationStore: Capture raw session observations
- LearningStore: Persist compressed learnings
- MemoryCompressor: AI/rule-based compression engine
- MemoryInjector: Context-aware memory retrieval
- MemoryObserver: Automatic observation capture

CLI commands (skillkit memory):
- status, search, list, show, compress, export
- import, clear, add, rate, config

TUI integration:
- New Memory screen with tabs (Learnings/Observations/Search)
- useMemory hook for state management
- Updated navigation and keybindings

Code quality improvements:
- Replaced nested ternaries with explicit functions
- Added named constants for magic numbers
- Simplified navigation with lookup map

* feat: add marketplace, testing, CI/CD, workflows, and fix dry-run bug

New Features:
- Skill Marketplace: Aggregates skills from GitHub repos with caching
- Skill Testing Framework: 18+ assertion types for skill validation
- CI/CD Integration: Templates for GitHub Actions, GitLab CI, CircleCI
- Workflow Orchestration: Wave-based parallel skill execution
- Session Management: Pause/resume support with state persistence
- Agent Execution: CLI spawning for claude/codex/gemini/opencode/goose

New CLI Commands:
- skillkit marketplace - Browse and install from marketplace
- skillkit test - Run skill tests with assertions
- skillkit run - Execute skills with orchestration
- skillkit status - Show session state
- skillkit pause/resume - Session management
- skillkit workflow - Workflow management

New TUI Screens:
- Marketplace browser with search
- History viewer with session details
- Workflow management screen

Bug Fix:
- Fixed dry-run mode in memory compress command (Devin review)
  The --dry-run flag now properly prevents storing learnings

* fix: add missing yaml dependency to @skillkit/cli

* chore: update pnpm-lock.yaml

* fix: address 7 bugs identified by Devin code review

- Fix MemoryIndexStore ignoring isGlobal flag (memory-index.ts)
- Fix ESM runtime crash using require('yaml') in test runner (runner.ts)
- Fix ESM runtime crash using require('node:fs') in MarketplaceAggregator (aggregator.ts)
- Fix ESM runtime crash using require('node:fs') in SessionManager (manager.ts)
- Fix memory rate command parsing rating from --content instead of positional arg (memory.ts)
- Fix SkillExecutionEngine emitting failed status for paused executions (engine.ts)
- Fix run command misclassifying directories as skill markdown files (run.ts)

* fix: address CodeRabbit/Devin review issues (batch 2)

- Fix resume skipping checkpoint handling in engine.ts
- Add paused status guard before completeExecution call
- Fix NaN% progress when totalSteps=0 in Execute.tsx
- Fix effectiveness ?? instead of || to preserve 0% values in compressor.ts
- Clear cache on source change in aggregator.ts addSource/removeSource

* fix: address critical and major CodeRabbit/Devin issues (batch 3)

Security fixes:
- Remove shell: true from spawn to prevent shell injection (agents.ts)
- Add safe regex test with ReDoS protection (engine.ts)
- Add security warning for verification commands (engine.ts)

Bug fixes:
- Fix global memory index path to use ~/.skillkit/ (compressor.ts, memory-index.ts)
- Add task_complete events and verification to resumeExecution (engine.ts)
- Handle absolute URLs in skill entries (aggregator.ts)
- Implement actual port availability check (runner.ts)
- Remove invalid JUnit report format (templates.ts)
- Add crash guard to workflow list command (workflow/list.ts)

* fix: address remaining CodeRabbit/Devin issues (batch 4)

- ReDoS protection: Add pattern validator to reject dangerous regex patterns
  (nested quantifiers, overlapping alternations, excessive quantifiers)
- Add missing 'cancelled' status message in execution engine
- Make completedAt/durationMs optional in TaskExecutionResult
- Fix tag filter to skip untagged tests when tags are specified
- Improve error-solution matching: require keyword similarity + solution indicator
- Validate --limit and sanitize --tags in memory/marketplace CLI commands
- Guard against missing arrays when importing YAML learnings
- Escape YAML frontmatter values to prevent invalid output
- Preserve original learning source when merging learnings
- Fix keyword double-counting in memory index search
- Normalize keywords by stripping punctuation for better matching
2026-01-23 18:12:15 +00:00
Rohit Ghumare b008a46b8d fix: address remaining CodeRabbit/Devin issues (batch 4)
- ReDoS protection: Add pattern validator to reject dangerous regex patterns
  (nested quantifiers, overlapping alternations, excessive quantifiers)
- Add missing 'cancelled' status message in execution engine
- Make completedAt/durationMs optional in TaskExecutionResult
- Fix tag filter to skip untagged tests when tags are specified
- Improve error-solution matching: require keyword similarity + solution indicator
- Validate --limit and sanitize --tags in memory/marketplace CLI commands
- Guard against missing arrays when importing YAML learnings
- Escape YAML frontmatter values to prevent invalid output
- Preserve original learning source when merging learnings
- Fix keyword double-counting in memory index search
- Normalize keywords by stripping punctuation for better matching
2026-01-23 18:01:56 +00:00
Rohit Ghumare ed90080786 fix: address critical and major CodeRabbit/Devin issues (batch 3)
Security fixes:
- Remove shell: true from spawn to prevent shell injection (agents.ts)
- Add safe regex test with ReDoS protection (engine.ts)
- Add security warning for verification commands (engine.ts)

Bug fixes:
- Fix global memory index path to use ~/.skillkit/ (compressor.ts, memory-index.ts)
- Add task_complete events and verification to resumeExecution (engine.ts)
- Handle absolute URLs in skill entries (aggregator.ts)
- Implement actual port availability check (runner.ts)
- Remove invalid JUnit report format (templates.ts)
- Add crash guard to workflow list command (workflow/list.ts)
2026-01-23 17:40:45 +00:00
Rohit Ghumare b701bb5f47 fix: address CodeRabbit/Devin review issues (batch 2)
- Fix resume skipping checkpoint handling in engine.ts
- Add paused status guard before completeExecution call
- Fix NaN% progress when totalSteps=0 in Execute.tsx
- Fix effectiveness ?? instead of || to preserve 0% values in compressor.ts
- Clear cache on source change in aggregator.ts addSource/removeSource
2026-01-23 16:55:29 +00:00
Rohit Ghumare 1c4c9a794f fix: address 7 bugs identified by Devin code review
- Fix MemoryIndexStore ignoring isGlobal flag (memory-index.ts)
- Fix ESM runtime crash using require('yaml') in test runner (runner.ts)
- Fix ESM runtime crash using require('node:fs') in MarketplaceAggregator (aggregator.ts)
- Fix ESM runtime crash using require('node:fs') in SessionManager (manager.ts)
- Fix memory rate command parsing rating from --content instead of positional arg (memory.ts)
- Fix SkillExecutionEngine emitting failed status for paused executions (engine.ts)
- Fix run command misclassifying directories as skill markdown files (run.ts)
2026-01-23 16:18:38 +00:00
Rohit Ghumare cb37ebeca7 chore: update pnpm-lock.yaml 2026-01-23 16:02:47 +00:00
Rohit Ghumare 7053d1a2b2 fix: add missing yaml dependency to @skillkit/cli 2026-01-23 16:01:00 +00:00
Rohit Ghumare 1ea5ddd4c7 feat: add marketplace, testing, CI/CD, workflows, and fix dry-run bug
New Features:
- Skill Marketplace: Aggregates skills from GitHub repos with caching
- Skill Testing Framework: 18+ assertion types for skill validation
- CI/CD Integration: Templates for GitHub Actions, GitLab CI, CircleCI
- Workflow Orchestration: Wave-based parallel skill execution
- Session Management: Pause/resume support with state persistence
- Agent Execution: CLI spawning for claude/codex/gemini/opencode/goose

New CLI Commands:
- skillkit marketplace - Browse and install from marketplace
- skillkit test - Run skill tests with assertions
- skillkit run - Execute skills with orchestration
- skillkit status - Show session state
- skillkit pause/resume - Session management
- skillkit workflow - Workflow management

New TUI Screens:
- Marketplace browser with search
- History viewer with session details
- Workflow management screen

Bug Fix:
- Fixed dry-run mode in memory compress command (Devin review)
  The --dry-run flag now properly prevents storing learnings
2026-01-23 15:50:54 +00:00
Rohit Ghumare 720532c020 feat: add session memory system for cross-agent learning
Implements a lightweight, local-first memory system that works across
all 17 AI coding agents. Key features:

- YAML-based storage (no databases or external services)
- Three memory layers: Session, Project, and Global
- AI-powered compression of observations into learnings
- Cross-agent memory injection with relevance matching
- Progressive disclosure for token efficiency

Core modules:
- ObservationStore: Capture raw session observations
- LearningStore: Persist compressed learnings
- MemoryCompressor: AI/rule-based compression engine
- MemoryInjector: Context-aware memory retrieval
- MemoryObserver: Automatic observation capture

CLI commands (skillkit memory):
- status, search, list, show, compress, export
- import, clear, add, rate, config

TUI integration:
- New Memory screen with tabs (Learnings/Observations/Search)
- useMemory hook for state management
- Updated navigation and keybindings

Code quality improvements:
- Replaced nested ternaries with explicit functions
- Added named constants for magic numbers
- Simplified navigation with lookup map
2026-01-23 14:24:16 +00:00
Rohit Ghumare bc12775e0e docs: add README files to all packages 2026-01-23 09:58:16 +00:00
99 changed files with 20775 additions and 866 deletions
+271 -371
View File
@@ -5,463 +5,324 @@
[![CI](https://github.com/rohitg00/skillkit/actions/workflows/ci.yml/badge.svg)](https://github.com/rohitg00/skillkit/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
**The universal skills platform for AI coding agents.** Install, manage, translate, and sync skills across 17+ AI tools with smart recommendations.
## One CLI. 17 AI Agents. Zero Lock-in.
**Write skills once, use everywhere.** SkillKit is the universal platform that lets your AI coding skills work across Claude Code, Cursor, Codex, Windsurf, GitHub Copilot, and 12 more agents.
```bash
npm install -g skillkit && skillkit
npm install -g skillkit
```
## Why SkillKit?
## The Problem
| Problem | SkillKit Solution |
|---------|------------------|
| Skills only work with one agent | **Cross-agent translation** - use any skill with any agent |
| Don't know which skills to install | **Smart recommendations** - project-aware suggestions |
| Config fragmented across agents | **One config, all agents** - sync everywhere |
| Manual skill discovery | **Task-based search** - find skills by what you need |
You've built amazing skills for Claude Code. Now you want to try Cursor. Or your team uses different agents. Your options:
## 30-Second Quick Start
1. **Rewrite everything** - each agent has different formats, directories, and conventions
2. **Pick one agent** - lock yourself in, miss out on innovations
3. **Give up on skills** - lose the productivity gains
## The Solution
```bash
# Install globally
# Install a skill for ALL your agents at once
skillkit install anthropics/skills --agent claude-code,cursor,windsurf
# Or translate existing skills between any agents
skillkit translate my-skill --from claude --to cursor,codex,copilot
# Get smart recommendations based on your project
skillkit recommend
# > 92% match: vercel-react-best-practices
# > 87% match: tailwind-v4-patterns
# > 85% match: nextjs-app-router
```
![SkillKit Demo](https://raw.githubusercontent.com/rohitg00/skillkit/main/skillkit.gif)
## What Makes SkillKit Different
| Feature | Without SkillKit | With SkillKit |
|---------|-----------------|---------------|
| **Multi-Agent Support** | Manual rewrite for each agent | One command, all agents |
| **Skill Discovery** | Search GitHub manually | Smart recommendations for your stack |
| **Format Translation** | Learn each agent's format | Automatic conversion (17 formats) |
| **Context Sync** | Configure each agent separately | One config, synced everywhere |
| **Session Memory** | Knowledge dies with each session | Persistent learning across agents |
| **Skill Testing** | Hope it works | Test framework with assertions |
## 5-Minute Quick Start
```bash
# 1. Install SkillKit globally
npm install -g skillkit
# Get personalized skill recommendations for your project
# 2. Launch the interactive TUI (easiest way to start)
skillkit
# Or use CLI commands directly:
# 3. Get personalized skill recommendations
skillkit recommend
# Install top-rated skills
# 4. Install skills from the marketplace
skillkit install anthropics/skills
# Launch interactive TUI
skillkit
# 5. Sync to your AI agent
skillkit sync
```
## Key Features
### Smart Recommendations
Analyzes your project and suggests the best skills:
```bash
skillkit recommend
# Project: my-app (Next.js + TypeScript + Tailwind)
#
# Recommended Skills:
# 92% ██████████ vercel-react-best-practices
# 87% █████████░ tailwind-v4-patterns
# 85% █████████░ nextjs-app-router
```
## Core Features
### Cross-Agent Translation
Use any skill with any agent - automatic format conversion:
Use any skill with any agent. SkillKit automatically converts between formats:
```bash
# Translate a Claude skill to Cursor format
skillkit translate react-patterns --to cursor
# Translate all skills for a new agent
skillkit translate --all --to antigravity
# Translate all your skills to a new agent
skillkit translate --all --to windsurf
# Preview translation without writing
skillkit translate my-skill --to codex --dry-run
```
### Project Context Sync
Configure once, sync to all your agents:
**Supported Agents:** Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Antigravity, Amp, Clawdbot, Droid, GitHub Copilot, Goose, Kilo, Kiro, Roo, Trae, Windsurf, Universal
### Smart Recommendations
SkillKit analyzes your project and suggests the perfect skills:
```bash
# Analyze project and create context
skillkit context init
skillkit recommend
# Sync your config to all detected agents
skillkit context sync --all
# Project: my-app (Next.js + TypeScript + Tailwind)
#
# Recommended Skills:
# 92% vercel-react-best-practices
# 87% tailwind-v4-patterns
# 85% nextjs-app-router
# 78% typescript-strict-mode
```
## Interactive TUI
Filter by task, category, or minimum score:
Launch the beautiful terminal interface:
```bash
skillkit recommend --search "auth" # Task-based search
skillkit recommend --category security # Category filter
skillkit recommend --min-score 80 # Quality threshold
```
### Session Memory System
Your AI agents learn, but that knowledge dies with the session. SkillKit captures learnings and makes them persistent:
```bash
# Compress session observations into reusable learnings
skillkit memory compress
# Search past learnings
skillkit memory search "authentication patterns"
# Export a learning as a shareable skill
skillkit memory export auth-insight --output auth-patterns.md
# Share memory across projects
skillkit memory --global
```
### Skill Marketplace
Browse and install from curated skill repositories:
```bash
# Browse all available skills
skillkit marketplace
# Search for specific skills
skillkit marketplace search "react hooks"
# Filter by tags
skillkit marketplace --tags typescript,testing
# Refresh the skill index
skillkit marketplace refresh
```
### Interactive TUI
Beautiful terminal interface for visual skill management:
```bash
skillkit ui
# or simply
# or just
skillkit
```
![SkillKit TUI](docs/img/skillkit-ui.png)
**Navigation:** `h` Home | `b` Browse | `r` Recommend | `t` Translate | `c` Context | `l` List | `s` Sync | `q` Quit
**Features:**
- Browse 33+ skill repositories
- Smart skill recommendations based on your project
- Install skills with one keystroke
- Multi-agent installation support
- Cross-agent skill translation
- Responsive design for all terminal sizes
### Skill Testing Framework
**Navigation:**
- `h` Home | `b` Browse | `r` Recommend | `l` List | `s` Sync | `,` Config
- `↑↓` Navigate | `Enter` Select | `Esc` Back | `q` Quit
- `m` Multi-agent selection | `/` Search
### Compatible With
| Agent | Status |
|-------|--------|
| Claude Code | ✅ Native |
| OpenAI Codex | ✅ Native |
| Cursor | ✅ Native |
| Gemini CLI | ✅ Native |
| OpenCode | ✅ Native |
| Antigravity | ✅ Native |
| Amp | ✅ Native |
| Clawdbot | ✅ Native |
| Droid (Factory) | ✅ Native |
| GitHub Copilot | ✅ Native |
| Goose | ✅ Native |
| Kilo Code | ✅ Native |
| Kiro CLI | ✅ Native |
| Roo Code | ✅ Native |
| Trae | ✅ Native |
| Windsurf | ✅ Native |
| *Any markdown-config agent* | ✅ Universal |
## Features
- **Smart Recommendations**: AI-powered skill suggestions based on your project stack
- **Cross-Agent Translation**: Convert skills between any of 17+ agent formats
- **Project Context Sync**: One config that syncs to all your agents
- **Interactive TUI**: Beautiful terminal interface for managing skills
- **Multi-Agent Support**: Works with Claude Code, Cursor, Codex, Windsurf, and 13+ more
- **Multi-Platform Git**: GitHub, GitLab, Bitbucket, and local paths
- **CI/CD Friendly**: Non-interactive flags for automation (`--skills`, `--all`, `--yes`)
- **Zero Config**: Auto-detects your agent and configures appropriately
## Installation
Test your skills with built-in assertions:
```bash
# Global install (recommended)
npm install -g skillkit
# Run all skill tests
skillkit test
# Or use without installing
npx skillkit <command>
# Test specific skills
skillkit test ./my-skill
# Or with other package managers
pnpm add -g skillkit
yarn global add skillkit
bun add -g skillkit
# Run tests with specific tags
skillkit test --tags unit,integration
# JSON output for CI
skillkit test --json
```
## Quick Start
### Workflow Orchestration
Compose skills into multi-step workflows:
```bash
# 1. Get recommendations for your project
skillkit recommend
# List available workflows
skillkit workflow list
# 2. Install recommended skills
skillkit install anthropics/skills
# Run a workflow
skillkit workflow run feature-development
# 3. Sync to your agent
skillkit sync
# Or just launch the TUI and do it all interactively
skillkit
# Create new workflow
skillkit workflow create my-workflow
```
## Popular Skill Repositories
### CI/CD Integration
Install skills from these community repositories:
Generate CI/CD templates for automated skill management:
```bash
# Anthropic's official skill marketplace
skillkit install anthropics/skills
# GitHub Actions
skillkit cicd github-action
# Vercel's React & Next.js best practices
skillkit install vercel-labs/agent-skills/skills
# GitLab CI
skillkit cicd gitlab-ci
# Pre-commit hooks
skillkit cicd pre-commit
```
![SkillKit Demo](https://raw.githubusercontent.com/rohitg00/skillkit/main/skillkit.gif)
## Supported Agents (17)
| Repository | Skills | Description |
|------------|--------|-------------|
| [anthropics/skills](https://github.com/anthropics/skills) | `pdf`, `xlsx`, `docx`, etc. | Official Claude Code skill marketplace |
| [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) | `vercel-react-best-practices`, `web-design-guidelines` | React/Next.js optimization & UI review |
| Agent | Format | Skills Directory |
|-------|--------|------------------|
| Claude Code | SKILL.md | `.claude/skills/` |
| Cursor | MDC (.mdc) | `.cursor/skills/` |
| Codex | SKILL.md | `.codex/skills/` |
| Gemini CLI | SKILL.md | `.gemini/skills/` |
| OpenCode | SKILL.md | `.opencode/skills/` |
| Antigravity | SKILL.md | `.antigravity/skills/` |
| Amp | SKILL.md | `.amp/skills/` |
| Clawdbot | SKILL.md | `skills/` |
| Droid (Factory) | SKILL.md | `.factory/skills/` |
| GitHub Copilot | Markdown | `.github/skills/` |
| Goose | SKILL.md | `.goose/skills/` |
| Kilo Code | SKILL.md | `.kilocode/skills/` |
| Kiro CLI | SKILL.md | `.kiro/skills/` |
| Roo Code | SKILL.md | `.roo/skills/` |
| Trae | SKILL.md | `.trae/skills/` |
| Windsurf | Markdown | `.windsurf/skills/` |
| Universal | SKILL.md | `skills/` |
## All Commands
## Commands
### `skillkit ui` / `skillkit`
Launch the interactive Terminal User Interface (TUI) for managing skills.
### Skill Management
```bash
skillkit ui # Explicit TUI launch
skillkit # Launch TUI if no arguments provided
skillkit install <source> # Install skills from GitHub/GitLab/Bitbucket/local
skillkit remove <skills> # Remove installed skills
skillkit update [skills] # Update skills from source
skillkit list # List installed skills
skillkit enable <skills> # Enable specific skills
skillkit disable <skills> # Disable specific skills
skillkit sync # Sync skills to agent config
skillkit read <skills> # Read skill content for AI
```
**TUI Features:**
- **Browse**: Discover skills from 33+ repositories
- **Recommend**: Get smart skill suggestions for your project
- **List**: View all installed skills
- **Sync**: Sync skills across multiple agents
- **Settings**: Configure SkillKit preferences
**Keyboard Shortcuts:**
- `h` - Home screen
- `b` - Browse skills marketplace
- `r` - Smart recommendations
- `l` - List installed skills
- `s` - Sync skills across agents
- `,` - Settings
- `↑↓` - Navigate lists
- `Enter` - Select / Install
- `m` - Multi-agent selection (when viewing skills)
- `/` - Search skills
- `Esc` - Return to home
- `q` - Quit
### `skillkit install <source>`
Install skills from various sources.
### Discovery & Recommendations
```bash
# GitHub (default)
skillkit install owner/repo
skillkit install https://github.com/owner/repo
# Install from a subdirectory
skillkit install owner/repo/skills
# GitLab
skillkit install gitlab:owner/repo
skillkit install https://gitlab.com/owner/repo
# Bitbucket
skillkit install bitbucket:owner/repo
# Local path
skillkit install ./my-skills
skillkit install ~/dev/skills
# Options
--list # List available skills without installing
--skills=pdf,xlsx # Install specific skills only (CI/CD)
--all # Install all discovered skills
--yes # Skip confirmation prompts
--global # Install to global directory
--force # Overwrite existing skills
--provider=gitlab # Force specific provider
--agent=cursor # Install to specific agent (can specify multiple)
skillkit recommend # Get smart recommendations
skillkit marketplace # Browse skill marketplace
skillkit marketplace search # Search marketplace
```
### `skillkit sync`
Sync installed skills to your agent's config file.
### Translation & Context
```bash
skillkit sync
skillkit sync --agent cursor
skillkit sync --output AGENTS.md
skillkit sync --enabled-only
skillkit translate # Translate between formats
skillkit context init # Initialize project context
skillkit context sync # Sync context to agents
```
### `skillkit recommend`
Get smart skill recommendations based on your project's tech stack.
### Memory System
```bash
skillkit recommend # Analyze current directory
skillkit recommend --path ./my-app # Analyze specific project
skillkit recommend --verbose # Show detailed match reasons
skillkit recommend --limit 5 # Limit results
skillkit recommend --min-score 50 # Only show high matches
skillkit recommend --category security # Filter by category
skillkit recommend --search "auth" # Search skills by task
skillkit recommend --update # Update skill index
skillkit recommend --json # Output as JSON
skillkit memory status # View memory status
skillkit memory search # Search learnings
skillkit memory compress # Compress observations
skillkit memory export # Export as skill
```
### `skillkit translate`
Translate skills between different agent formats.
### Testing & Workflows
```bash
skillkit translate react-skill --to cursor # Translate to Cursor format
skillkit translate ./skill --from claude --to windsurf # Explicit source/target
skillkit translate --all --to cursor # Translate all installed skills
skillkit translate react-skill --to cursor --dry-run # Preview without writing
skillkit test # Run skill tests
skillkit workflow run # Execute workflow
skillkit cicd # Generate CI/CD templates
```
**Supported translations:** All 17 agents can translate to/from each other.
### `skillkit context`
Manage project context for cross-agent synchronization.
### Utilities
```bash
skillkit context init # Analyze project and create context
skillkit context show # Display current context
skillkit context export # Export context to file
skillkit context import ./context.yaml # Import context from file
skillkit context sync --agent cursor # Sync context to specific agent
skillkit context sync --all # Sync to all detected agents
skillkit init # Initialize in project
skillkit validate # Validate skill format
skillkit create # Create new skill
```
### `skillkit read <skills>`
Read skill content for AI agent consumption.
```bash
skillkit read pdf
skillkit read pdf,xlsx,docx # Multiple skills
```
### `skillkit list`
List all installed skills.
```bash
skillkit list
skillkit list --enabled
skillkit list --json
```
### `skillkit enable/disable <skills>`
Toggle skills on/off without removing them.
```bash
skillkit enable pdf xlsx
skillkit disable docx
```
### `skillkit update [skills]`
Update skills from their original sources.
```bash
skillkit update # Update all
skillkit update pdf xlsx # Update specific
```
### `skillkit remove <skills>`
Remove installed skills.
```bash
skillkit remove pdf xlsx
```
### `skillkit init`
Initialize skillkit in a project.
```bash
skillkit init
skillkit init --agent cursor
skillkit init --list # List supported agents
```
### `skillkit validate <path>`
Validate skills against the [Agent Skills specification](https://agentskills.io/specification).
```bash
skillkit validate ./my-skill # Validate single skill
skillkit validate ./skills --all # Validate all skills in directory
```
### `skillkit create <skill-name>`
Create a new skill with proper structure and template.
```bash
skillkit create my-skill # Basic skill
skillkit create my-skill --full # Include all directories (references, scripts, assets)
skillkit create my-skill --scripts # Include scripts directory
skillkit create my-skill --references # Include references directory
skillkit create my-skill --assets # Include assets directory
skillkit create my-skill --dir ./skills # Create in specific directory
```
## Supported Agents
| Agent | Config File | Project Path | Global Path |
|-------|-------------|--------------|-------------|
| Claude Code | `AGENTS.md` | `.claude/skills/` | `~/.claude/skills/` |
| Cursor | `.cursorrules` | `.cursor/skills/` | `~/.cursor/skills/` |
| Codex | `AGENTS.md` | `.codex/skills/` | `~/.codex/skills/` |
| Gemini CLI | `GEMINI.md` | `.gemini/skills/` | `~/.gemini/skills/` |
| OpenCode | `AGENTS.md` | `.opencode/skills/` | `~/.config/opencode/skills/` |
| Antigravity | `AGENTS.md` | `.antigravity/skills/` | `~/.gemini/antigravity/skills/` |
| Amp | `AGENTS.md` | `.agents/skills/` | `~/.config/agents/skills/` |
| Clawdbot | `AGENTS.md` | `skills/` | `~/.clawdbot/skills/` |
| Droid (Factory) | `AGENTS.md` | `.factory/skills/` | `~/.factory/skills/` |
| GitHub Copilot | `AGENTS.md` | `.github/skills/` | `~/.copilot/skills/` |
| Goose | `AGENTS.md` | `.goose/skills/` | `~/.config/goose/skills/` |
| Kilo Code | `AGENTS.md` | `.kilocode/skills/` | `~/.kilocode/skills/` |
| Kiro CLI | `AGENTS.md` | `.kiro/skills/` | `~/.kiro/skills/` |
| Roo Code | `AGENTS.md` | `.roo/skills/` | `~/.roo/skills/` |
| Trae | `AGENTS.md` | `.trae/skills/` | `~/.trae/skills/` |
| Windsurf | `AGENTS.md` | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` |
| Universal | `AGENTS.md` | `.agent/skills/` | `~/.agent/skills/` |
## Creating Skills
Use `skillkit create <name>` to scaffold a new skill, or create manually:
### Quick Start
A skill is a directory with a `SKILL.md` file:
```
my-skill/
├── SKILL.md # Required: Instructions for the AI
├── references/ # Optional: Documentation
├── scripts/ # Optional: Helper scripts
└── assets/ # Optional: Templates, configs
```bash
skillkit create my-skill
```
### SKILL.md Format
### Manual Creation
Follows the [Agent Skills specification](https://agentskills.io/specification):
Create a `SKILL.md` file following the [Agent Skills specification](https://agentskills.io/specification):
```markdown
---
name: my-skill
description: What this skill does and when to use it. Include trigger keywords.
description: What this skill does and when to use it
license: MIT
compatibility: Requires Node.js 18+
metadata:
author: your-org
author: your-name
version: "1.0"
---
# My Skill
Instructions for the AI agent on how to use this skill.
Instructions for the AI agent.
## When to Use
- Scenario 1
- Scenario 2
## Steps
1. First step
2. Second step
```
| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Lowercase alphanumeric with hyphens (max 64 chars) |
| `description` | Yes | What it does and when to use it (max 1024 chars) |
| `license` | No | License name or reference |
| `compatibility` | No | Environment requirements |
| `metadata` | No | Arbitrary key-value pairs |
## CI/CD Usage
```yaml
# GitHub Actions example
- name: Setup skills
run: |
npx skillkit install owner/skills --skills=lint,test,deploy --yes
npx skillkit sync --yes
```
## Programmatic API
```typescript
@@ -471,41 +332,68 @@ import {
discoverSkills,
detectAgent,
getAdapter,
// Recommendations
RecommendationEngine,
analyzeProject,
// Translation
translateSkill,
translateSkillFile,
// Recommendations
RecommendationEngine,
analyzeProject,
// Context
ContextManager,
initContext,
syncToAllAgents,
// Memory
createMemoryCompressor,
createMemoryInjector,
LearningStore,
// Marketplace
createMarketplaceAggregator,
// Testing
SkillTestRunner,
// Workflows
WorkflowOrchestrator,
} from 'skillkit';
// Find all installed skills
const skills = findAllSkills(searchDirs);
// Example: Translate and install
const skill = await translateSkill(skillContent, 'cursor');
console.log(skill.content);
// Detect current agent
const agent = await detectAgent();
// Generate config
const adapter = getAdapter(agent);
const config = adapter.generateConfig(skills);
// Get smart recommendations
// Example: Get recommendations
const engine = new RecommendationEngine();
const profile = await analyzeProject('./my-project');
const recommendations = engine.recommend(profile, skills);
const recs = engine.recommend(profile);
```
// Translate skills between agents
const result = translateSkill(skillContent, 'cursor');
console.log(result.content); // Cursor MDC format
## Popular Skill Repositories
// Manage project context
const ctx = new ContextManager('./my-project');
await ctx.init();
await syncToAllAgents(ctx.getContext());
| Repository | Description |
|------------|-------------|
| [anthropics/skills](https://github.com/anthropics/skills) | Official Claude Code marketplace - PDF, XLSX, DOCX processing |
| [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) | React/Next.js best practices, web design guidelines |
## Installation Options
```bash
# npm (recommended)
npm install -g skillkit
# pnpm
pnpm add -g skillkit
# yarn
yarn global add skillkit
# bun
bun add -g skillkit
# npx (no install)
npx skillkit <command>
```
## Configuration
@@ -523,14 +411,26 @@ disabledSkills:
- deprecated-skill
```
## Why SkillKit Exists
AI coding agents are amazing, but the ecosystem is fragmented:
- **Skills don't transfer** between agents
- **Knowledge dies** when sessions end
- **No standard** for skill quality or testing
- **Manual discovery** of useful skills
SkillKit solves these problems with a universal platform that works across all major AI coding agents.
## License
Apache License 2.0 - see [LICENSE](LICENSE) for details.
## Contributing
Contributions welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) before submitting a pull request.
Contributions welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md).
## Acknowledgments
## Links
Implements the [Agent Skills](https://agentskills.io) open format, originally developed by Anthropic and adopted by leading AI development tools.
- [Agent Skills Specification](https://agentskills.io/specification)
- [GitHub Repository](https://github.com/rohitg00/skillkit)
- [NPM Package](https://www.npmjs.com/package/skillkit)
+41
View File
@@ -0,0 +1,41 @@
# SkillKit
Universal skills manager for AI coding agents. Install, manage, and sync skills across 17+ AI agents including Claude Code, Cursor, Codex, Gemini CLI, and more.
## Installation
```bash
npm install -g skillkit
```
## Quick Start
```bash
# Initialize skillkit in your project
skillkit init
# Install a skill
skillkit install github.com/anthropics/courses:prompt-eng/interactive-tutorial
# List installed skills
skillkit list
# Launch interactive TUI
skillkit ui
```
## Features
- **17+ Agent Support**: Claude Code, Cursor, Codex, Gemini CLI, Windsurf, GitHub Copilot, and more
- **Universal Skill Translation**: Convert skills between different agent formats
- **Smart Recommendations**: Get skill suggestions based on your project stack
- **Project Context Sync**: One config, all agents
- **Interactive TUI**: Browse, install, and manage skills visually
## Documentation
Full documentation: https://github.com/rohitg00/skillkit
## License
Apache-2.0
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "skillkit",
"version": "1.3.0",
"version": "1.4.0",
"description": "Universal skills loader for AI coding agents - supports Claude Code, Codex, Cursor, Antigravity, OpenCode, Gemini CLI and more",
"type": "module",
"bin": {
+28
View File
@@ -19,6 +19,20 @@ import {
TranslateCommand,
ContextCommand,
RecommendCommand,
StatusCommand,
PauseCommand,
ResumeCommand,
WorkflowRunCommand,
WorkflowListCommand,
WorkflowCreateCommand,
RunCommand,
TestCommand,
MarketplaceCommand,
MemoryCommand,
SettingsCommand,
CICDCommand,
TeamCommand,
PluginCommand,
} from '@skillkit/cli';
const __filename = fileURLToPath(import.meta.url);
@@ -51,5 +65,19 @@ cli.register(UICommand);
cli.register(TranslateCommand);
cli.register(ContextCommand);
cli.register(RecommendCommand);
cli.register(StatusCommand);
cli.register(PauseCommand);
cli.register(ResumeCommand);
cli.register(WorkflowRunCommand);
cli.register(WorkflowListCommand);
cli.register(WorkflowCreateCommand);
cli.register(RunCommand);
cli.register(TestCommand);
cli.register(MarketplaceCommand);
cli.register(MemoryCommand);
cli.register(SettingsCommand);
cli.register(CICDCommand);
cli.register(TeamCommand);
cli.register(PluginCommand);
cli.runExit(process.argv.slice(2));
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "skillkit-monorepo",
"version": "1.3.0",
"version": "1.4.0",
"private": true,
"description": "Universal skills loader for AI coding agents - Monorepo",
"type": "module",
+206
View File
@@ -0,0 +1,206 @@
# @skillkit/agents
[![npm version](https://img.shields.io/npm/v/@skillkit/agents.svg)](https://www.npmjs.com/package/@skillkit/agents)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
**Agent adapters for SkillKit** - configuration and detection for 17 AI coding agents.
## Installation
```bash
npm install @skillkit/agents
```
## Supported Agents (17)
| Agent | Config Format | Project Skills | Global Skills |
|-------|--------------|----------------|---------------|
| Claude Code | SKILL.md | `.claude/skills/` | `~/.claude/skills/` |
| Cursor | MDC (.mdc) | `.cursor/skills/` | `~/.cursor/skills/` |
| Codex | SKILL.md | `.codex/skills/` | `~/.codex/skills/` |
| Gemini CLI | SKILL.md | `.gemini/skills/` | `~/.gemini/skills/` |
| OpenCode | SKILL.md | `.opencode/skills/` | `~/.config/opencode/skills/` |
| Antigravity | SKILL.md | `.antigravity/skills/` | `~/.gemini/antigravity/skills/` |
| Amp | SKILL.md | `.agents/skills/` | `~/.config/agents/skills/` |
| Clawdbot | SKILL.md | `skills/` | `~/.clawdbot/skills/` |
| Droid (Factory) | SKILL.md | `.factory/skills/` | `~/.factory/skills/` |
| GitHub Copilot | Markdown | `.github/skills/` | `~/.copilot/skills/` |
| Goose | SKILL.md | `.goose/skills/` | `~/.config/goose/skills/` |
| Kilo Code | SKILL.md | `.kilocode/skills/` | `~/.kilocode/skills/` |
| Kiro CLI | SKILL.md | `.kiro/skills/` | `~/.kiro/skills/` |
| Roo Code | SKILL.md | `.roo/skills/` | `~/.roo/skills/` |
| Trae | SKILL.md | `.trae/skills/` | `~/.trae/skills/` |
| Windsurf | Markdown | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` |
| Universal | SKILL.md | `skills/` | `~/.agent/skills/` |
## Usage
### Get Agent Adapter
```typescript
import { getAdapter, AgentType } from '@skillkit/agents';
// Get adapter for specific agent
const adapter = getAdapter('claude-code');
console.log(adapter.name); // 'claude-code'
console.log(adapter.skillsDir); // '.claude/skills/'
console.log(adapter.globalSkillsDir); // '~/.claude/skills/'
console.log(adapter.configFile); // 'AGENTS.md'
console.log(adapter.format); // 'skill-md'
```
### Detect Installed Agents
```typescript
import { detectAgent, detectAllAgents } from '@skillkit/agents';
// Detect primary agent in current directory
const primary = await detectAgent();
console.log(primary); // 'claude-code'
// Detect all installed agents
const all = await detectAllAgents();
console.log(all); // ['claude-code', 'cursor', 'windsurf']
// Detect in specific directory
const agents = await detectAllAgents('./my-project');
```
### List All Adapters
```typescript
import { listAdapters, getAdapterNames } from '@skillkit/agents';
// Get all adapter configurations
const adapters = listAdapters();
adapters.forEach(adapter => {
console.log(`${adapter.name}: ${adapter.skillsDir}`);
});
// Get just the names
const names = getAdapterNames();
console.log(names); // ['claude-code', 'cursor', 'codex', ...]
```
### Generate Agent Config
```typescript
import { getAdapter } from '@skillkit/agents';
import { findAllSkills } from '@skillkit/core';
const adapter = getAdapter('cursor');
const skills = findAllSkills([adapter.skillsDir]);
// Generate config file content
const config = adapter.generateConfig(skills);
console.log(config);
```
### Get Skills Directory
```typescript
import { getAdapter } from '@skillkit/agents';
import { homedir } from 'os';
const adapter = getAdapter('claude-code');
// Project-local skills directory
const projectDir = adapter.skillsDir; // '.claude/skills/'
// Global skills directory
const globalDir = adapter.globalSkillsDir.replace('~', homedir());
// '/Users/you/.claude/skills/'
```
## Adapter Interface
```typescript
interface AgentAdapter {
// Agent identifier
name: AgentType;
// Display name
displayName: string;
// Skill file format
format: 'skill-md' | 'mdc' | 'markdown';
// Project skills directory (relative)
skillsDir: string;
// Global skills directory (with ~)
globalSkillsDir: string;
// Config file name
configFile: string;
// Generate config from skills
generateConfig(skills: Skill[]): string;
// Parse existing config
parseConfig(content: string): Skill[];
}
```
## Agent Types
```typescript
type AgentType =
| 'claude-code'
| 'cursor'
| 'codex'
| 'gemini-cli'
| 'opencode'
| 'antigravity'
| 'amp'
| 'clawdbot'
| 'droid'
| 'github-copilot'
| 'goose'
| 'kilo'
| 'kiro-cli'
| 'roo'
| 'trae'
| 'windsurf'
| 'universal';
```
## Format Details
### SKILL.md Format
Used by most agents. YAML frontmatter + Markdown content:
```markdown
---
name: my-skill
description: What this skill does
---
# My Skill
Instructions...
```
### MDC Format (Cursor)
Cursor-specific format with globs and alwaysApply:
```
---
description: What this skill does
globs: ["**/*.tsx"]
alwaysApply: false
---
Instructions...
```
### Markdown Format
Plain markdown used by Windsurf and Copilot:
```markdown
# Skill Name
Instructions for the agent...
```
## Documentation
Full documentation: https://github.com/rohitg00/skillkit
## License
Apache-2.0
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/agents",
"version": "1.3.0",
"version": "1.4.0",
"description": "Agent adapters for SkillKit - supports 17+ AI coding agents",
"type": "module",
"main": "./dist/index.js",
+196
View File
@@ -0,0 +1,196 @@
# @skillkit/cli
[![npm version](https://img.shields.io/npm/v/@skillkit/cli.svg)](https://www.npmjs.com/package/@skillkit/cli)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
**Command-line interface for SkillKit** - install, manage, translate, and sync skills across 17 AI coding agents.
## Installation
```bash
npm install -g @skillkit/cli
# or
npm install -g skillkit # includes CLI
```
## Quick Start
```bash
# Get skill recommendations for your project
skillkit recommend
# Install skills from GitHub
skillkit install anthropics/skills
# Translate skills between agents
skillkit translate my-skill --to cursor
# Launch interactive TUI
skillkit ui
```
## All Commands
### Skill Management
```bash
skillkit install <source> # Install from GitHub/GitLab/Bitbucket/local
skillkit remove <skills> # Remove installed skills
skillkit update [skills] # Update skills from source
skillkit list # List installed skills
skillkit enable <skills> # Enable specific skills
skillkit disable <skills> # Disable specific skills
skillkit sync # Sync to agent config
skillkit read <skills> # Read skill content
```
### Discovery & Recommendations
```bash
skillkit recommend # Project-based recommendations
skillkit recommend --search "auth" # Task-based search
skillkit recommend --category security # Filter by category
skillkit recommend --min-score 80 # Quality threshold
skillkit marketplace # Browse skills
skillkit marketplace search "react" # Search marketplace
skillkit marketplace --tags typescript # Filter by tags
skillkit marketplace refresh # Refresh index
```
### Translation
```bash
skillkit translate <skill> --to <agent> # Translate single skill
skillkit translate --all --to cursor # Translate all skills
skillkit translate skill --dry-run # Preview without writing
```
### Context Management
```bash
skillkit context init # Analyze project, create context
skillkit context show # Display current context
skillkit context sync --all # Sync to all detected agents
skillkit context export # Export context file
```
### Session Memory
```bash
skillkit memory status # View memory status
skillkit memory search "auth" # Search learnings
skillkit memory list # List all learnings
skillkit memory compress # Compress observations
skillkit memory export <id> # Export as skill
skillkit memory add # Add manual learning
skillkit memory --global # Use global scope
```
### Testing & Workflows
```bash
skillkit test # Run all skill tests
skillkit test ./my-skill # Test specific skill
skillkit test --tags unit # Run tagged tests
skillkit workflow list # List workflows
skillkit workflow run <name> # Execute workflow
skillkit workflow create # Create new workflow
skillkit cicd github-action # Generate GitHub Actions
skillkit cicd gitlab-ci # Generate GitLab CI
skillkit cicd pre-commit # Generate pre-commit hook
```
### Utilities
```bash
skillkit init # Initialize in project
skillkit init --agent cursor # Initialize for specific agent
skillkit validate ./skill # Validate skill format
skillkit create my-skill # Create new skill
```
## Install Options
```bash
skillkit install owner/repo # GitHub repository
skillkit install gitlab:owner/repo # GitLab repository
skillkit install ./local/path # Local directory
# Options
--list # List available skills without installing
--skills=pdf,xlsx # Install specific skills
--all # Install all discovered skills
--yes # Skip confirmation prompts
--global # Install globally
--force # Overwrite existing
--agent=cursor,windsurf # Install to specific agents
```
## Programmatic Usage
```typescript
import {
installCommand,
listCommand,
syncCommand,
translateCommand,
recommendCommand,
} from '@skillkit/cli';
// Install skills programmatically
await installCommand('anthropics/skills', {
agent: ['claude-code', 'cursor'],
yes: true,
});
// List installed skills
const skills = await listCommand({ json: true });
// Sync to agent
await syncCommand({ all: true });
// Translate skill
await translateCommand('my-skill', {
to: 'cursor',
dryRun: false,
});
// Get recommendations
const recs = await recommendCommand({
path: './my-project',
minScore: 70,
});
```
## CI/CD Usage
```yaml
# GitHub Actions example
- name: Setup skills
run: |
npx skillkit install owner/skills --skills=lint,test --yes
npx skillkit sync --yes
```
## Supported Agents
| Agent | Format |
|-------|--------|
| Claude Code | SKILL.md |
| Cursor | MDC (.mdc) |
| Codex | SKILL.md |
| Gemini CLI | SKILL.md |
| Windsurf | Markdown |
| GitHub Copilot | Markdown |
| + 11 more | SKILL.md |
## Documentation
Full documentation: https://github.com/rohitg00/skillkit
## License
Apache-2.0
+3 -2
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/cli",
"version": "1.3.0",
"version": "1.4.0",
"description": "CLI commands for SkillKit",
"type": "module",
"main": "./dist/index.js",
@@ -26,7 +26,8 @@
"clipanion": "^4.0.0-rc.4",
"got": "^14.4.1",
"isomorphic-git": "^1.27.1",
"ora": "^8.1.0"
"ora": "^8.1.0",
"yaml": "^2.7.0"
},
"devDependencies": {
"@types/node": "^22.10.5",
+380
View File
@@ -0,0 +1,380 @@
import { Command, Option } from 'clipanion';
import chalk from 'chalk';
import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
type CICDProvider = 'github' | 'gitlab' | 'circleci';
const GITHUB_ACTIONS_WORKFLOW = `name: SkillKit CI
on:
push:
branches: [main, master]
paths:
- '.skillkit/**'
- 'skills/**'
- '.claude/skills/**'
- '.cursor/skills/**'
pull_request:
branches: [main, master]
paths:
- '.skillkit/**'
- 'skills/**'
- '.claude/skills/**'
- '.cursor/skills/**'
jobs:
validate:
name: Validate Skills
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install SkillKit
run: npm install -g skillkit
- name: Validate Skills
run: skillkit validate --all
- name: List Skills
run: skillkit list
test:
name: Test Skills
runs-on: ubuntu-latest
needs: validate
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install SkillKit
run: npm install -g skillkit
- name: Run Skill Tests
run: skillkit test --all
continue-on-error: true
sync:
name: Sync Skills
runs-on: ubuntu-latest
needs: validate
if: github.event_name == 'push'
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install SkillKit
run: npm install -g skillkit
- name: Sync Skills to All Agents
run: skillkit sync --yes
`;
const GITLAB_CI = `stages:
- validate
- test
- sync
variables:
NODE_VERSION: "20"
.skillkit-base:
image: node:\${NODE_VERSION}
before_script:
- npm install -g skillkit
rules:
- changes:
- .skillkit/**/*
- skills/**/*
- .claude/skills/**/*
- .cursor/skills/**/*
validate:
extends: .skillkit-base
stage: validate
script:
- skillkit validate --all
- skillkit list
test:
extends: .skillkit-base
stage: test
script:
- skillkit test --all
allow_failure: true
needs:
- validate
sync:
extends: .skillkit-base
stage: sync
script:
- skillkit sync --yes
needs:
- validate
rules:
- if: $CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH == "master"
changes:
- .skillkit/**/*
- skills/**/*
- .claude/skills/**/*
- .cursor/skills/**/*
`;
const CIRCLECI_CONFIG = `version: 2.1
executors:
node:
docker:
- image: cimg/node:20.0
jobs:
validate:
executor: node
steps:
- checkout
- run:
name: Install SkillKit
command: npm install -g skillkit
- run:
name: Validate Skills
command: skillkit validate --all
- run:
name: List Skills
command: skillkit list
test:
executor: node
steps:
- checkout
- run:
name: Install SkillKit
command: npm install -g skillkit
- run:
name: Run Skill Tests
command: skillkit test --all || true
sync:
executor: node
steps:
- checkout
- run:
name: Install SkillKit
command: npm install -g skillkit
- run:
name: Sync Skills
command: skillkit sync --yes
workflows:
skillkit:
jobs:
- validate:
filters:
branches:
only:
- main
- master
- test:
requires:
- validate
- sync:
requires:
- validate
filters:
branches:
only:
- main
- master
`;
/**
* CICD command - initialize CI/CD workflows for skill validation and testing
*/
export class CICDCommand extends Command {
static override paths = [['cicd', 'init']];
static override usage = Command.Usage({
description: 'Initialize CI/CD workflows for skill validation',
details: `
The cicd command sets up continuous integration workflows to automatically
validate and test skills on every push or pull request.
Supported providers: github, gitlab, circleci
`,
examples: [
['Initialize GitHub Actions workflow', '$0 cicd init'],
['Initialize GitLab CI', '$0 cicd init --provider gitlab'],
['Initialize CircleCI', '$0 cicd init --provider circleci'],
['Initialize all providers', '$0 cicd init --all'],
['Force overwrite existing files', '$0 cicd init --force'],
],
});
// Provider selection
provider = Option.String('--provider,-p', 'github', {
description: 'CI/CD provider (github, gitlab, circleci)',
});
// Generate for all providers
all = Option.Boolean('--all,-a', false, {
description: 'Generate workflows for all supported providers',
});
// Force overwrite
force = Option.Boolean('--force,-f', false, {
description: 'Overwrite existing workflow files',
});
// Project path
targetPath = Option.String('--path', {
description: 'Project path (default: current directory)',
});
async execute(): Promise<number> {
const projectPath = this.targetPath || process.cwd();
const providers: CICDProvider[] = this.all
? ['github', 'gitlab', 'circleci']
: [this.provider as CICDProvider];
console.log(chalk.cyan('Initializing CI/CD workflows...'));
console.log();
let success = true;
let created = false;
for (const provider of providers) {
const result = this.createWorkflow(projectPath, provider);
if (result.skipped) {
console.log(chalk.yellow(` ${result.message}`));
continue;
}
if (!result.success) {
success = false;
console.error(chalk.red(` ${result.message}`));
continue;
}
created = true;
console.log(chalk.green(` ✓ ${result.message}`));
}
if (success) {
console.log();
console.log(
created
? chalk.green('CI/CD workflows initialized successfully!')
: chalk.yellow('CI/CD workflows already exist; nothing to do.')
);
console.log();
if (created) {
console.log(chalk.dim('The workflows will run on push/PR to validate your skills.'));
console.log(chalk.dim('Commit the generated files to enable CI/CD.'));
}
}
return success ? 0 : 1;
}
private createWorkflow(
projectPath: string,
provider: CICDProvider
): { success: boolean; message: string; skipped?: boolean } {
switch (provider) {
case 'github':
return this.createGitHubActions(projectPath);
case 'gitlab':
return this.createGitLabCI(projectPath);
case 'circleci':
return this.createCircleCI(projectPath);
default:
return { success: false, message: `Unknown provider: ${provider}` };
}
}
private createGitHubActions(projectPath: string): { success: boolean; message: string; skipped?: boolean } {
const workflowDir = join(projectPath, '.github', 'workflows');
const workflowFile = join(workflowDir, 'skillkit.yml');
if (existsSync(workflowFile) && !this.force) {
return {
success: true,
message: `GitHub Actions workflow already exists (use --force to overwrite)`,
skipped: true,
};
}
try {
mkdirSync(workflowDir, { recursive: true });
writeFileSync(workflowFile, GITHUB_ACTIONS_WORKFLOW);
return { success: true, message: `Created ${workflowFile}` };
} catch (error) {
return { success: false, message: `Failed to create GitHub workflow: ${error}` };
}
}
private createGitLabCI(projectPath: string): { success: boolean; message: string; skipped?: boolean } {
const ciFile = join(projectPath, '.gitlab-ci.yml');
if (existsSync(ciFile) && !this.force) {
// Check if skillkit jobs already exist for better messaging
try {
const content = readFileSync(ciFile, 'utf-8');
if (content.includes('skillkit')) {
return {
success: true,
message: `.gitlab-ci.yml already contains SkillKit config (use --force to overwrite)`,
skipped: true,
};
}
return {
success: true,
message: `.gitlab-ci.yml already exists (use --force to overwrite)`,
skipped: true,
};
} catch (error) {
return {
success: false,
message: `Failed to read .gitlab-ci.yml: ${error}`,
};
}
}
try {
writeFileSync(ciFile, GITLAB_CI);
return { success: true, message: `Created ${ciFile}` };
} catch (error) {
return { success: false, message: `Failed to create GitLab CI config: ${error}` };
}
}
private createCircleCI(projectPath: string): { success: boolean; message: string; skipped?: boolean } {
const circleDir = join(projectPath, '.circleci');
const configFile = join(circleDir, 'config.yml');
if (existsSync(configFile) && !this.force) {
return {
success: true,
message: `CircleCI config already exists (use --force to overwrite)`,
skipped: true,
};
}
try {
mkdirSync(circleDir, { recursive: true });
writeFileSync(configFile, CIRCLECI_CONFIG);
return { success: true, message: `Created ${configFile}` };
} catch (error) {
return { success: false, message: `Failed to create CircleCI config: ${error}` };
}
}
}
+12
View File
@@ -13,3 +13,15 @@ export { UICommand } from './ui.js';
export { TranslateCommand } from './translate.js';
export { ContextCommand } from './context.js';
export { RecommendCommand } from './recommend.js';
export { StatusCommand } from './status.js';
export { PauseCommand } from './pause.js';
export { ResumeCommand } from './resume.js';
export { WorkflowRunCommand, WorkflowListCommand, WorkflowCreateCommand } from './workflow/index.js';
export { RunCommand } from './run.js';
export { TestCommand } from './test.js';
export { MarketplaceCommand } from './marketplace.js';
export { MemoryCommand } from './memory.js';
export { SettingsCommand } from './settings.js';
export { CICDCommand } from './cicd.js';
export { TeamCommand } from './team.js';
export { PluginCommand } from './plugin.js';
+250
View File
@@ -0,0 +1,250 @@
import { Command, Option } from 'clipanion';
import chalk from 'chalk';
import ora from 'ora';
import {
createMarketplaceAggregator,
type MarketplaceSearchOptions,
} from '@skillkit/core';
/**
* Marketplace command - browse and install skills from the marketplace
*/
export class MarketplaceCommand extends Command {
static override paths = [['marketplace'], ['market'], ['mp']];
static override usage = Command.Usage({
description: 'Browse and install skills from the marketplace',
details: `
The marketplace command lets you discover and install skills
from curated repositories.
Skills are aggregated from multiple sources including:
- composioHQ/awesome-claude-code-skills
- anthropics/courses
- User-added custom sources
`,
examples: [
['Browse marketplace', '$0 marketplace'],
['Search for skills', '$0 marketplace search typescript'],
['Refresh marketplace index', '$0 marketplace refresh'],
['Show popular tags', '$0 marketplace tags'],
['List sources', '$0 marketplace sources'],
],
});
action = Option.String({ required: false });
query = Option.String({ required: false });
limit = Option.String('--limit,-l', {
description: 'Limit results',
});
tags = Option.String('--tags,-t', {
description: 'Filter by tags (comma-separated)',
});
source = Option.String('--source,-s', {
description: 'Filter by source',
});
json = Option.Boolean('--json,-j', false, {
description: 'Output as JSON',
});
async execute(): Promise<number> {
const marketplace = createMarketplaceAggregator();
switch (this.action) {
case 'search':
return this.searchSkills(marketplace);
case 'refresh':
return this.refreshIndex(marketplace);
case 'tags':
return this.showTags(marketplace);
case 'sources':
return this.showSources(marketplace);
default:
// Default: browse/search
if (this.query || this.action) {
return this.searchSkills(marketplace);
}
return this.browseMarketplace(marketplace);
}
}
private async browseMarketplace(marketplace: ReturnType<typeof createMarketplaceAggregator>): Promise<number> {
const spinner = ora('Loading marketplace...').start();
try {
const index = await marketplace.getIndex();
spinner.stop();
if (this.json) {
console.log(JSON.stringify({
totalSkills: index.totalCount,
sources: index.sources.length,
updatedAt: index.updatedAt,
}));
return 0;
}
console.log(chalk.bold('Skill Marketplace\n'));
console.log(`Total skills: ${chalk.cyan(index.totalCount)}`);
console.log(`Sources: ${chalk.cyan(index.sources.length)}`);
console.log(`Last updated: ${chalk.dim(new Date(index.updatedAt).toLocaleString())}\n`);
// Show sample skills
console.log(chalk.bold('Featured Skills:\n'));
const featured = index.skills.slice(0, 10);
for (const skill of featured) {
console.log(` ${chalk.cyan(skill.name)}`);
if (skill.description) {
console.log(` ${chalk.dim(skill.description.slice(0, 60))}${skill.description.length > 60 ? '...' : ''}`);
}
console.log(` ${chalk.dim(`Source: ${skill.source.name}`)}`);
console.log();
}
console.log(chalk.dim('Use "skillkit marketplace search <query>" to search for skills.'));
console.log(chalk.dim('Use "skillkit marketplace tags" to see popular tags.'));
return 0;
} catch (error) {
spinner.fail('Failed to load marketplace');
console.error(chalk.red(error instanceof Error ? error.message : String(error)));
return 1;
}
}
private async searchSkills(marketplace: ReturnType<typeof createMarketplaceAggregator>): Promise<number> {
const query = this.query || this.action;
// Validate and parse limit
let limit = 20;
if (this.limit) {
const parsed = parseInt(this.limit, 10);
if (isNaN(parsed) || parsed <= 0) {
console.error(chalk.red('Invalid --limit value. Must be a positive number.'));
return 1;
}
limit = parsed;
}
// Sanitize tags - filter out empty strings
const tags = this.tags
?.split(',')
.map((t) => t.trim())
.filter((t) => t.length > 0);
const spinner = ora(`Searching for "${query}"...`).start();
try {
const options: MarketplaceSearchOptions = {
query: query || undefined,
limit,
tags: tags && tags.length > 0 ? tags : undefined,
source: this.source,
};
const result = await marketplace.search(options);
spinner.stop();
if (this.json) {
console.log(JSON.stringify(result));
return 0;
}
if (result.skills.length === 0) {
console.log(chalk.yellow(`No skills found${query ? ` matching "${query}"` : ''}.`));
return 0;
}
console.log(chalk.bold(`Found ${result.total} skill(s):\n`));
for (const skill of result.skills) {
console.log(`${chalk.cyan(skill.name)} ${chalk.dim(`(${skill.source.name})`)}`);
if (skill.description) {
console.log(` ${skill.description}`);
}
if (skill.tags.length > 0) {
console.log(` Tags: ${chalk.dim(skill.tags.join(', '))}`);
}
console.log();
}
if (result.total > result.skills.length) {
console.log(chalk.dim(`Showing ${result.skills.length} of ${result.total} results. Use --limit to see more.`));
}
return 0;
} catch (error) {
spinner.fail('Search failed');
console.error(chalk.red(error instanceof Error ? error.message : String(error)));
return 1;
}
}
private async refreshIndex(marketplace: ReturnType<typeof createMarketplaceAggregator>): Promise<number> {
const spinner = ora('Refreshing marketplace index...').start();
try {
const index = await marketplace.refresh();
spinner.succeed(`Marketplace refreshed: ${index.totalCount} skills from ${index.sources.length} sources`);
return 0;
} catch (error) {
spinner.fail('Refresh failed');
console.error(chalk.red(error instanceof Error ? error.message : String(error)));
return 1;
}
}
private async showTags(marketplace: ReturnType<typeof createMarketplaceAggregator>): Promise<number> {
const spinner = ora('Loading tags...').start();
try {
const tags = await marketplace.getPopularTags(30);
spinner.stop();
if (this.json) {
console.log(JSON.stringify(tags));
return 0;
}
console.log(chalk.bold('Popular Tags:\n'));
for (const { tag, count } of tags) {
const bar = '█'.repeat(Math.min(count, 20));
console.log(` ${tag.padEnd(15)} ${chalk.cyan(bar)} ${count}`);
}
return 0;
} catch (error) {
spinner.fail('Failed to load tags');
console.error(chalk.red(error instanceof Error ? error.message : String(error)));
return 1;
}
}
private async showSources(marketplace: ReturnType<typeof createMarketplaceAggregator>): Promise<number> {
const sources = marketplace.getSources();
if (this.json) {
console.log(JSON.stringify(sources));
return 0;
}
console.log(chalk.bold('Skill Sources:\n'));
for (const source of sources) {
console.log(`${chalk.cyan(source.name)} ${source.official ? chalk.green('(official)') : ''}`);
console.log(` ${chalk.dim(`${source.owner}/${source.repo}`)}`);
if (source.description) {
console.log(` ${source.description}`);
}
console.log();
}
return 0;
}
}
+872
View File
@@ -0,0 +1,872 @@
import { Command, Option } from 'clipanion';
import chalk from 'chalk';
import {
ObservationStore,
LearningStore,
getMemoryPaths,
initializeMemoryDirectory,
getMemoryStatus,
createMemoryCompressor,
createMemoryInjector,
type Learning,
} from '@skillkit/core';
/**
* Memory command - manage session memory across AI agents
*/
export class MemoryCommand extends Command {
static override paths = [['memory'], ['mem']];
static override usage = Command.Usage({
description: 'Manage session memory across AI coding agents',
details: `
The memory command helps you view, search, and manage learnings
captured from coding sessions across all AI agents.
Subcommands:
- status: Show current memory status
- search: Search memories by query
- list: List all learnings
- show: Show a specific learning
- compress: Compress observations into learnings
- export: Export a learning as a skill
- import: Import memories from another project
- clear: Clear session observations
- add: Manually add a learning
- rate: Rate a learning's effectiveness
- config: Configure memory settings
`,
examples: [
['Show memory status', '$0 memory status'],
['Search memories', '$0 memory search "authentication"'],
['Search global memories', '$0 memory search --global "react hooks"'],
['List project learnings', '$0 memory list'],
['List global learnings', '$0 memory list --global'],
['Show a learning', '$0 memory show <id>'],
['Compress observations', '$0 memory compress'],
['Export as skill', '$0 memory export <id> --name my-skill'],
['Clear session', '$0 memory clear'],
['Add manual learning', '$0 memory add --title "..." --content "..."'],
['Rate effectiveness', '$0 memory rate <id> 85'],
],
});
// Subcommand (status, search, list, show, compress, export, import, clear, add, rate, config)
action = Option.String({ required: false });
// Second argument (query for search, id for show/export/rate)
arg = Option.String({ required: false });
// Third argument (rating value for rate command)
ratingArg = Option.String({ required: false });
// Global scope
global = Option.Boolean('--global,-g', false, {
description: 'Use global memories instead of project',
});
// Tags filter
tags = Option.String('--tags,-t', {
description: 'Filter by tags (comma-separated)',
});
// Limit results
limit = Option.String('--limit,-l', {
description: 'Maximum number of results',
});
// Title for add
title = Option.String('--title', {
description: 'Title for new learning',
});
// Content for add
content = Option.String('--content,-c', {
description: 'Content for new learning',
});
// Name for export
name = Option.String('--name,-n', {
description: 'Name for exported skill',
});
// Output file
output = Option.String('--output,-o', {
description: 'Output file path',
});
// Input file
input = Option.String('--input,-i', {
description: 'Input file path',
});
// Keep learnings when clearing
keepLearnings = Option.Boolean('--keep-learnings', false, {
description: 'Keep learnings when clearing',
});
// Dry run
dryRun = Option.Boolean('--dry-run', false, {
description: 'Preview without making changes',
});
// JSON output
json = Option.Boolean('--json,-j', false, {
description: 'Output in JSON format',
});
// Verbose output
verbose = Option.Boolean('--verbose,-v', false, {
description: 'Show detailed output',
});
async execute(): Promise<number> {
const action = this.action || 'status';
switch (action) {
case 'status':
return this.showStatus();
case 'search':
return this.searchMemories();
case 'list':
return this.listLearnings();
case 'show':
return this.showLearning();
case 'compress':
return this.compressObservations();
case 'export':
return this.exportLearning();
case 'import':
return this.importMemories();
case 'clear':
return this.clearMemory();
case 'add':
return this.addLearning();
case 'rate':
return this.rateLearning();
case 'config':
return this.showConfig();
default:
console.error(chalk.red(`Unknown action: ${action}`));
console.log(chalk.gray('Available actions: status, search, list, show, compress, export, import, clear, add, rate, config'));
return 1;
}
}
/**
* Show memory status
*/
private async showStatus(): Promise<number> {
const projectPath = process.cwd();
const status = getMemoryStatus(projectPath);
const paths = getMemoryPaths(projectPath);
// Get counts from stores
const observationStore = new ObservationStore(projectPath);
const projectLearningStore = new LearningStore('project', projectPath);
const globalLearningStore = new LearningStore('global');
const sessionObservations = status.hasObservations ? observationStore.count() : 0;
const projectLearnings = status.hasLearnings ? projectLearningStore.count() : 0;
const globalLearnings = status.hasGlobalLearnings ? globalLearningStore.count() : 0;
const sessionId = status.hasObservations ? observationStore.getSessionId() : null;
if (this.json) {
console.log(JSON.stringify({
...status,
sessionObservations,
projectLearnings,
globalLearnings,
sessionId,
paths,
}, null, 2));
return 0;
}
console.log(chalk.bold('\nMemory Status\n'));
// Session observations
console.log(chalk.cyan('Session:'));
console.log(` Observations: ${sessionObservations}`);
if (sessionId) {
console.log(` Session ID: ${chalk.gray(sessionId.slice(0, 8))}`);
}
console.log();
// Project learnings
console.log(chalk.cyan('Project:'));
console.log(` Learnings: ${projectLearnings}`);
console.log(` Path: ${chalk.gray(status.projectMemoryExists ? paths.projectMemoryDir : 'Not initialized')}`);
console.log();
// Global learnings
console.log(chalk.cyan('Global:'));
console.log(` Learnings: ${globalLearnings}`);
console.log(` Path: ${chalk.gray(status.globalMemoryExists ? paths.globalMemoryDir : 'Not initialized')}`);
console.log();
// Recommendations
if (sessionObservations >= 50) {
console.log(chalk.yellow('💡 You have many uncompressed observations. Consider running:'));
console.log(chalk.gray(' skillkit memory compress'));
}
return 0;
}
/**
* Search memories
*/
private async searchMemories(): Promise<number> {
const query = this.arg;
if (!query) {
console.error(chalk.red('Error: Search query is required'));
console.log(chalk.gray('Usage: skillkit memory search "your query"'));
return 1;
}
const projectPath = process.cwd();
const injector = createMemoryInjector(projectPath);
// Validate and parse limit
let maxLearnings = 10;
if (this.limit) {
const parsed = parseInt(this.limit, 10);
if (isNaN(parsed) || parsed <= 0) {
console.log(chalk.red('Invalid --limit value. Must be a positive number.'));
return 1;
}
maxLearnings = parsed;
}
// Sanitize tags - filter out empty strings
const tags = this.tags
?.split(',')
.map((t) => t.trim())
.filter((t) => t.length > 0);
const results = injector.search(query, {
includeGlobal: this.global,
tags: tags && tags.length > 0 ? tags : undefined,
maxLearnings,
minRelevance: 0,
});
if (this.json) {
console.log(JSON.stringify(results, null, 2));
return 0;
}
if (results.length === 0) {
console.log(chalk.yellow(`No memories found for: "${query}"`));
return 0;
}
console.log(chalk.bold(`\nFound ${results.length} memories:\n`));
for (const { learning, relevanceScore, matchedBy } of results) {
console.log(`${chalk.cyan('●')} ${chalk.bold(learning.title)}`);
console.log(` ID: ${chalk.gray(learning.id.slice(0, 8))}`);
console.log(` Relevance: ${this.formatScore(relevanceScore)}%`);
console.log(` Tags: ${learning.tags.join(', ')}`);
console.log(` Scope: ${learning.scope}`);
if (this.verbose) {
console.log(` Matched: ${this.formatMatchedBy(matchedBy)}`);
console.log(` Created: ${new Date(learning.createdAt).toLocaleDateString()}`);
console.log(` Uses: ${learning.useCount}`);
}
// Show excerpt
const excerpt = learning.content.slice(0, 100);
console.log(` ${chalk.gray(excerpt)}${learning.content.length > 100 ? '...' : ''}`);
console.log();
}
return 0;
}
/**
* List all learnings
*/
private async listLearnings(): Promise<number> {
const projectPath = process.cwd();
const store = new LearningStore(
this.global ? 'global' : 'project',
this.global ? undefined : projectPath
);
let learnings = store.getAll();
// Filter by tags if specified
if (this.tags) {
const tagList = this.tags.split(',').map((t) => t.trim().toLowerCase());
learnings = learnings.filter((l) =>
l.tags.some((t) => tagList.includes(t.toLowerCase()))
);
}
// Limit results
const limit = this.limit ? parseInt(this.limit, 10) : learnings.length;
learnings = learnings.slice(0, limit);
if (this.json) {
console.log(JSON.stringify(learnings, null, 2));
return 0;
}
const scope = this.global ? 'Global' : 'Project';
console.log(chalk.bold(`\n${scope} Learnings (${learnings.length}):\n`));
if (learnings.length === 0) {
console.log(chalk.gray('No learnings found.'));
console.log(chalk.gray('\nCapture learnings by running skills or add manually:'));
console.log(chalk.gray(' skillkit memory add --title "..." --content "..."'));
return 0;
}
for (const learning of learnings) {
const effectiveness = learning.effectiveness !== undefined
? ` [${this.formatScore(learning.effectiveness)}%]`
: '';
console.log(`${chalk.cyan('●')} ${learning.title}${chalk.green(effectiveness)}`);
console.log(` ${chalk.gray(learning.id.slice(0, 8))} | ${learning.tags.join(', ')} | ${learning.useCount} uses`);
if (this.verbose) {
const excerpt = learning.content.slice(0, 80);
console.log(` ${chalk.gray(excerpt)}${learning.content.length > 80 ? '...' : ''}`);
}
}
console.log();
return 0;
}
/**
* Show a specific learning
*/
private async showLearning(): Promise<number> {
const id = this.arg;
if (!id) {
console.error(chalk.red('Error: Learning ID is required'));
console.log(chalk.gray('Usage: skillkit memory show <id>'));
return 1;
}
const projectPath = process.cwd();
// Try project store first
let learning = new LearningStore('project', projectPath).getById(id);
// Try global store
if (!learning) {
learning = new LearningStore('global').getById(id);
}
// Try matching by prefix
if (!learning) {
const projectLearnings = new LearningStore('project', projectPath).getAll();
const globalLearnings = new LearningStore('global').getAll();
const all = [...projectLearnings, ...globalLearnings];
learning = all.find((l) => l.id.startsWith(id));
}
if (!learning) {
console.error(chalk.red(`Learning not found: ${id}`));
return 1;
}
if (this.json) {
console.log(JSON.stringify(learning, null, 2));
return 0;
}
console.log(chalk.bold(`\n${learning.title}\n`));
console.log(chalk.gray(`ID: ${learning.id}`));
console.log(chalk.gray(`Scope: ${learning.scope}`));
console.log(chalk.gray(`Source: ${learning.source}`));
console.log(chalk.gray(`Tags: ${learning.tags.join(', ')}`));
if (learning.frameworks?.length) {
console.log(chalk.gray(`Frameworks: ${learning.frameworks.join(', ')}`));
}
if (learning.patterns?.length) {
console.log(chalk.gray(`Patterns: ${learning.patterns.join(', ')}`));
}
console.log(chalk.gray(`Created: ${new Date(learning.createdAt).toLocaleString()}`));
console.log(chalk.gray(`Updated: ${new Date(learning.updatedAt).toLocaleString()}`));
console.log(chalk.gray(`Uses: ${learning.useCount}`));
if (learning.effectiveness !== undefined) {
console.log(chalk.gray(`Effectiveness: ${this.formatScore(learning.effectiveness)}%`));
}
console.log(chalk.bold('\nContent:\n'));
console.log(learning.content);
console.log();
return 0;
}
/**
* Compress observations into learnings
*/
private async compressObservations(): Promise<number> {
const projectPath = process.cwd();
// Initialize memory directory if needed
initializeMemoryDirectory(projectPath);
const observationStore = new ObservationStore(projectPath);
const observations = observationStore.getAll();
if (observations.length === 0) {
console.log(chalk.yellow('No observations to compress.'));
return 0;
}
console.log(chalk.cyan(`Found ${observations.length} observations to compress...\n`));
const compressor = createMemoryCompressor(projectPath);
const compressionOptions = {
minObservations: 2,
additionalTags: this.tags?.split(',').map((t) => t.trim()),
};
if (this.dryRun) {
console.log(chalk.gray('(Dry run - no changes will be made)\n'));
// For dry-run, only compress without storing
const result = await compressor.compress(observations, compressionOptions);
console.log(chalk.green(`✓ Would compress ${result.stats.inputCount} observations into ${result.stats.outputCount} learnings\n`));
if (result.learnings.length > 0) {
console.log(chalk.bold('Learnings that would be created:'));
for (const learning of result.learnings) {
console.log(` ${chalk.cyan('●')} ${learning.title}`);
console.log(` Tags: ${learning.tags.join(', ')}`);
}
console.log();
}
return 0;
}
// Actual compression with storage
const { learnings, result } = await compressor.compressAndStore(observations, compressionOptions);
console.log(chalk.green(`✓ Compressed ${result.stats.inputCount} observations into ${result.stats.outputCount} learnings\n`));
if (learnings.length > 0) {
console.log(chalk.bold('New Learnings:'));
for (const learning of learnings) {
console.log(` ${chalk.cyan('●')} ${learning.title}`);
console.log(` Tags: ${learning.tags.join(', ')}`);
}
console.log();
}
if (result.processedObservationIds.length > 0) {
// Remove processed observations
const deleted = observationStore.deleteMany(result.processedObservationIds);
console.log(chalk.gray(`Cleared ${deleted} processed observations.`));
}
return 0;
}
/**
* Export a learning as a skill
*/
private async exportLearning(): Promise<number> {
const id = this.arg;
if (!id) {
console.error(chalk.red('Error: Learning ID is required'));
console.log(chalk.gray('Usage: skillkit memory export <id> --name my-skill'));
return 1;
}
const projectPath = process.cwd();
// Find the learning
let learning = new LearningStore('project', projectPath).getById(id);
if (!learning) {
learning = new LearningStore('global').getById(id);
}
// Try matching by prefix
if (!learning) {
const projectLearnings = new LearningStore('project', projectPath).getAll();
const globalLearnings = new LearningStore('global').getAll();
const all = [...projectLearnings, ...globalLearnings];
learning = all.find((l) => l.id.startsWith(id));
}
if (!learning) {
console.error(chalk.red(`Learning not found: ${id}`));
return 1;
}
// Generate skill name
const skillName = this.name || this.slugify(learning.title);
// Generate skill content
const skillContent = this.generateSkillContent(learning, skillName);
if (this.dryRun) {
console.log(chalk.gray('(Dry run preview)\n'));
console.log(skillContent);
return 0;
}
// Determine output path
const outputPath = this.output || `.skillkit/exports/${skillName}/SKILL.md`;
const { dirname } = await import('node:path');
const { existsSync, mkdirSync, writeFileSync } = await import('node:fs');
const outputDir = dirname(outputPath);
if (!existsSync(outputDir)) {
mkdirSync(outputDir, { recursive: true });
}
writeFileSync(outputPath, skillContent, 'utf-8');
console.log(chalk.green(`✓ Exported learning as skill: ${skillName}`));
console.log(chalk.gray(` Path: ${outputPath}`));
return 0;
}
/**
* Import memories from another project
*/
private async importMemories(): Promise<number> {
const inputPath = this.input || this.arg;
if (!inputPath) {
console.error(chalk.red('Error: Input path is required'));
console.log(chalk.gray('Usage: skillkit memory import --input <path>'));
return 1;
}
const { existsSync, readFileSync } = await import('node:fs');
const { resolve } = await import('node:path');
const fullPath = resolve(inputPath);
if (!existsSync(fullPath)) {
console.error(chalk.red(`File not found: ${fullPath}`));
return 1;
}
const projectPath = process.cwd();
const store = new LearningStore(
this.global ? 'global' : 'project',
this.global ? undefined : projectPath
);
try {
const content = readFileSync(fullPath, 'utf-8');
const { parse: parseYaml } = await import('yaml');
const data = parseYaml(content) as { learnings?: Learning[] };
if (!data.learnings || !Array.isArray(data.learnings)) {
console.error(chalk.red('Invalid memory file format'));
return 1;
}
let imported = 0;
for (const learning of data.learnings) {
if (this.dryRun) {
console.log(chalk.gray(`Would import: ${learning.title}`));
} else {
store.add({
source: 'imported',
title: learning.title,
content: learning.content,
// Default to empty arrays if not present in imported YAML
tags: Array.isArray(learning.tags) ? learning.tags : [],
frameworks: Array.isArray(learning.frameworks) ? learning.frameworks : [],
patterns: Array.isArray(learning.patterns) ? learning.patterns : [],
});
imported++;
}
}
if (this.dryRun) {
console.log(chalk.gray(`\n(Dry run - ${data.learnings.length} learnings would be imported)`));
} else {
console.log(chalk.green(`✓ Imported ${imported} learnings`));
}
return 0;
} catch (error) {
console.error(chalk.red(`Import failed: ${error}`));
return 1;
}
}
/**
* Clear session observations
*/
private async clearMemory(): Promise<number> {
const projectPath = process.cwd();
if (this.dryRun) {
const observationStore = new ObservationStore(projectPath);
const learningStore = new LearningStore('project', projectPath);
console.log(chalk.gray('(Dry run preview)\n'));
console.log(`Would clear ${observationStore.count()} observations`);
if (!this.keepLearnings) {
console.log(`Would clear ${learningStore.count()} learnings`);
}
return 0;
}
const observationStore = new ObservationStore(projectPath);
observationStore.clear();
console.log(chalk.green('✓ Cleared session observations'));
if (!this.keepLearnings) {
const learningStore = new LearningStore('project', projectPath);
learningStore.clear();
console.log(chalk.green('✓ Cleared project learnings'));
}
return 0;
}
/**
* Add a manual learning
*/
private async addLearning(): Promise<number> {
if (!this.title) {
console.error(chalk.red('Error: --title is required'));
console.log(chalk.gray('Usage: skillkit memory add --title "..." --content "..."'));
return 1;
}
if (!this.content) {
console.error(chalk.red('Error: --content is required'));
console.log(chalk.gray('Usage: skillkit memory add --title "..." --content "..."'));
return 1;
}
const projectPath = process.cwd();
const store = new LearningStore(
this.global ? 'global' : 'project',
this.global ? undefined : projectPath
);
const tags = this.tags?.split(',').map((t) => t.trim()) || [];
const learning = store.add({
source: 'manual',
title: this.title,
content: this.content,
tags,
});
console.log(chalk.green(`✓ Added learning: ${learning.title}`));
console.log(chalk.gray(` ID: ${learning.id}`));
return 0;
}
/**
* Rate a learning's effectiveness
*/
private async rateLearning(): Promise<number> {
const id = this.arg;
if (!id) {
console.error(chalk.red('Error: Learning ID is required'));
console.log(chalk.gray('Usage: skillkit memory rate <id> <rating>'));
return 1;
}
const rating = parseInt(this.ratingArg || '0', 10);
if (isNaN(rating) || rating < 0 || rating > 100) {
console.error(chalk.red('Error: Rating must be 0-100'));
console.log(chalk.gray('Usage: skillkit memory rate <id> <rating>'));
return 1;
}
const projectPath = process.cwd();
// Try project store first
const projectStore = new LearningStore('project', projectPath);
let learning = projectStore.getById(id);
let store = projectStore;
if (!learning) {
const globalStore = new LearningStore('global');
learning = globalStore.getById(id);
store = globalStore;
}
// Try prefix match
if (!learning) {
const projectLearnings = projectStore.getAll();
const globalStore = new LearningStore('global');
const globalLearnings = globalStore.getAll();
learning = projectLearnings.find((l) => l.id.startsWith(id));
if (learning) {
store = projectStore;
} else {
learning = globalLearnings.find((l) => l.id.startsWith(id));
if (learning) {
store = globalStore;
}
}
}
if (!learning) {
console.error(chalk.red(`Learning not found: ${id}`));
return 1;
}
store.setEffectiveness(learning.id, rating);
console.log(chalk.green(`✓ Rated "${learning.title}" as ${rating}% effective`));
return 0;
}
/**
* Show memory configuration
*/
private async showConfig(): Promise<number> {
const projectPath = process.cwd();
const paths = getMemoryPaths(projectPath);
if (this.json) {
console.log(JSON.stringify(paths, null, 2));
return 0;
}
console.log(chalk.bold('\nMemory Configuration\n'));
console.log(chalk.cyan('Paths:'));
console.log(` Project observations: ${chalk.gray(paths.observationsFile)}`);
console.log(` Project learnings: ${chalk.gray(paths.learningsFile)}`);
console.log(` Project index: ${chalk.gray(paths.indexFile)}`);
console.log(` Global learnings: ${chalk.gray(paths.globalLearningsFile)}`);
console.log(` Global index: ${chalk.gray(paths.globalIndexFile)}`);
console.log();
return 0;
}
/**
* Format relevance/effectiveness score with color
*/
private formatScore(score: number): string {
if (score >= 80) return chalk.green(score.toString());
if (score >= 50) return chalk.yellow(score.toString());
return chalk.red(score.toString());
}
/**
* Format matched by info
*/
private formatMatchedBy(matchedBy: {
frameworks: string[];
tags: string[];
keywords: string[];
patterns: string[];
}): string {
const parts: string[] = [];
if (matchedBy.frameworks.length > 0) {
parts.push(`frameworks: ${matchedBy.frameworks.join(', ')}`);
}
if (matchedBy.tags.length > 0) {
parts.push(`tags: ${matchedBy.tags.join(', ')}`);
}
if (matchedBy.keywords.length > 0) {
parts.push(`keywords: ${matchedBy.keywords.slice(0, 3).join(', ')}`);
}
if (matchedBy.patterns.length > 0) {
parts.push(`patterns: ${matchedBy.patterns.join(', ')}`);
}
return parts.join(' | ') || 'general';
}
/**
* Convert title to slug
*/
private slugify(text: string): string {
return text
.toLowerCase()
.replace(/[^a-z0-9]+/g, '-')
.replace(/^-|-$/g, '')
.slice(0, 50);
}
/**
* Escape a YAML scalar value if it contains special characters
*/
private escapeYamlValue(value: string): string {
// Check if value needs quoting (contains special YAML characters)
if (/[:#\[\]{}|>&*!?,'"\\@`]/.test(value) || value.includes('\n')) {
// Use double quotes and escape internal quotes/backslashes
return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
}
return value;
}
/**
* Generate skill content from learning
*/
private generateSkillContent(learning: Learning, skillName: string): string {
// Escape values that might contain special YAML characters
const escapedName = this.escapeYamlValue(skillName);
const escapedDesc = this.escapeYamlValue(learning.title);
const escapedTags = learning.tags.map((t) => this.escapeYamlValue(t));
const lines: string[] = [
'---',
`name: ${escapedName}`,
`description: ${escapedDesc}`,
`version: 1.0.0`,
`tags: [${escapedTags.join(', ')}]`,
`source: skillkit-memory`,
`sourceType: local`,
];
if (learning.frameworks?.length) {
const escapedFrameworks = learning.frameworks.map((f) => this.escapeYamlValue(f));
lines.push(`compatibility:`);
lines.push(` frameworks: [${escapedFrameworks.join(', ')}]`);
}
lines.push('---', '', `# ${learning.title}`, '');
if (learning.patterns?.length) {
lines.push(`## Patterns`, '');
for (const pattern of learning.patterns) {
lines.push(`- ${pattern}`);
}
lines.push('');
}
lines.push(`## Content`, '', learning.content, '');
lines.push(
'---',
'',
'*Exported from SkillKit session memory*',
`*Created: ${new Date(learning.createdAt).toLocaleDateString()}*`,
`*Uses: ${learning.useCount}*`
);
if (learning.effectiveness !== undefined) {
lines.push(`*Effectiveness: ${learning.effectiveness}%*`);
}
return lines.join('\n');
}
}
+71
View File
@@ -0,0 +1,71 @@
import { Command, Option } from 'clipanion';
import { resolve } from 'node:path';
import chalk from 'chalk';
import { SessionManager } from '@skillkit/core';
/**
* Pause command - pause current skill execution
*/
export class PauseCommand extends Command {
static override paths = [['pause']];
static override usage = Command.Usage({
description: 'Pause current skill execution for later resumption',
details: `
The pause command saves the current execution state so you can
continue later with "skillkit resume".
This is useful when you need to:
- Take a break from a long skill execution
- Handle an interruption
- Review progress before continuing
`,
examples: [
['Pause current execution', '$0 pause'],
],
});
// Project path
projectPath = Option.String('--path,-p', {
description: 'Project path (default: current directory)',
});
async execute(): Promise<number> {
const targetPath = resolve(this.projectPath || process.cwd());
const manager = new SessionManager(targetPath);
const state = manager.get();
if (!state) {
console.log(chalk.yellow('No active session found.'));
return 1;
}
if (!state.currentExecution) {
console.log(chalk.yellow('No skill execution in progress.'));
return 1;
}
if (state.currentExecution.status === 'paused') {
console.log(chalk.yellow('Execution is already paused.'));
console.log(chalk.dim('Resume with: skillkit resume'));
return 0;
}
const success = manager.pause();
if (success) {
const exec = state.currentExecution;
console.log(chalk.green('✓ Execution paused'));
console.log();
console.log(` Skill: ${chalk.bold(exec.skillName)}`);
console.log(` Progress: ${exec.currentStep}/${exec.totalSteps} tasks completed`);
console.log();
console.log(chalk.dim('Resume with: skillkit resume'));
console.log(chalk.dim('View status: skillkit status'));
return 0;
} else {
console.log(chalk.red('Failed to pause execution.'));
return 1;
}
}
}
+342
View File
@@ -0,0 +1,342 @@
/**
* Plugin Command
*
* Manage SkillKit plugins
*/
import { Command, Option } from 'clipanion';
import { join, isAbsolute, resolve, sep } from 'node:path';
import { homedir } from 'node:os';
import { existsSync, mkdirSync, copyFileSync, cpSync, rmSync } from 'node:fs';
import chalk from 'chalk';
import { createPluginManager, loadPlugin, loadPluginsFromDirectory } from '@skillkit/core';
export class PluginCommand extends Command {
static override paths = [['plugin']];
static override usage = Command.Usage({
description: 'Manage SkillKit plugins',
examples: [
['List installed plugins', '$0 plugin list'],
['Install a plugin', '$0 plugin install --source ./my-plugin'],
['Install from npm', '$0 plugin install --source skillkit-plugin-gitlab'],
['Uninstall a plugin', '$0 plugin uninstall --name my-plugin'],
['Enable a plugin', '$0 plugin enable --name my-plugin'],
['Disable a plugin', '$0 plugin disable --name my-plugin'],
],
});
action = Option.String({ required: true });
source = Option.String('--source,-s', { description: 'Plugin source (file path or npm package)' });
name = Option.String('--name,-n', { description: 'Plugin name' });
global = Option.Boolean('--global,-g', { description: 'Use global plugin directory' });
async execute(): Promise<number> {
const projectPath = this.global
? join(homedir(), '.skillkit')
: process.cwd();
const pluginManager = createPluginManager(projectPath);
// Auto-load plugins from directory
const pluginsDir = this.global
? join(projectPath, 'plugins')
: join(projectPath, '.skillkit', 'plugins');
try {
const plugins = await loadPluginsFromDirectory(pluginsDir);
for (const plugin of plugins) {
if (pluginManager.isPluginEnabled(plugin.metadata.name)) {
await pluginManager.register(plugin);
}
}
} catch {
// Plugins directory may not exist
}
try {
switch (this.action) {
case 'list':
return this.listPlugins(pluginManager);
case 'install':
return await this.installPlugin(pluginManager);
case 'uninstall':
return await this.uninstallPlugin(pluginManager);
case 'enable':
return this.enablePlugin(pluginManager);
case 'disable':
return this.disablePlugin(pluginManager);
case 'info':
return this.pluginInfo(pluginManager);
default:
this.context.stderr.write(chalk.red(`Unknown action: ${this.action}\n`));
this.context.stderr.write('Available actions: list, install, uninstall, enable, disable, info\n');
return 1;
}
} catch (err) {
this.context.stderr.write(chalk.red(`✗ ${err instanceof Error ? err.message : 'Unknown error'}\n`));
return 1;
}
}
private listPlugins(pluginManager: ReturnType<typeof createPluginManager>): number {
const plugins = pluginManager.listPlugins();
if (plugins.length === 0) {
this.context.stdout.write('No plugins installed.\n');
this.context.stdout.write('Use `skillkit plugin install --source <source>` to install a plugin.\n');
return 0;
}
this.context.stdout.write(chalk.cyan(`Installed Plugins (${plugins.length}):\n\n`));
for (const plugin of plugins) {
const enabled = pluginManager.isPluginEnabled(plugin.name);
const status = enabled
? chalk.green('enabled')
: chalk.gray('disabled');
this.context.stdout.write(chalk.cyan(` ${plugin.name}`) + ` v${plugin.version} [${status}]\n`);
if (plugin.description) {
this.context.stdout.write(chalk.gray(` ${plugin.description}\n`));
}
}
// Show registered extensions
const translators = pluginManager.getAllTranslators();
const providers = pluginManager.getAllProviders();
const commands = pluginManager.getAllCommands();
if (translators.size > 0 || providers.size > 0 || commands.length > 0) {
this.context.stdout.write(chalk.cyan('\nRegistered Extensions:\n'));
if (translators.size > 0) {
this.context.stdout.write(` Translators: ${Array.from(translators.keys()).join(', ')}\n`);
}
if (providers.size > 0) {
this.context.stdout.write(` Providers: ${Array.from(providers.keys()).join(', ')}\n`);
}
if (commands.length > 0) {
this.context.stdout.write(` Commands: ${commands.map((c) => c.name).join(', ')}\n`);
}
}
return 0;
}
/**
* Validate plugin name to prevent path traversal attacks
* Allows scoped npm names like @scope/name (mirrors loader.ts validation)
*/
private isValidPluginName(name: string): boolean {
if (!name) return false;
// Reject backslashes, path traversal sequences, and names starting with '.'
if (name.includes('\\') || name.includes('..') || name === '.' || name.startsWith('.')) {
return false;
}
// Allow scoped npm names (@scope/name) or simple names (no slashes)
// Use the same regex pattern as loader.ts validatePlugin
return /^(?:@[a-z0-9-]+\/)?[a-z0-9-]+$/.test(name);
}
private async installPlugin(pluginManager: ReturnType<typeof createPluginManager>): Promise<number> {
if (!this.source) {
this.context.stderr.write(chalk.red('--source is required for install\n'));
return 1;
}
// Expand tilde to home directory for all operations
const resolvedSource = this.source.startsWith('~')
? join(homedir(), this.source.slice(1))
: this.source;
this.context.stdout.write(`Installing plugin from ${this.source}...\n`);
const plugin = await loadPlugin(resolvedSource);
// Validate plugin name from metadata
const pluginName = plugin.metadata.name;
if (!this.isValidPluginName(pluginName)) {
this.context.stderr.write(chalk.red(`Invalid plugin name: ${pluginName}\n`));
return 1;
}
// Determine plugins directory
const projectPath = this.global
? join(homedir(), '.skillkit')
: process.cwd();
const pluginsDir = this.global
? join(projectPath, 'plugins')
: join(projectPath, '.skillkit', 'plugins');
// Persist plugin files to disk if source is a local file/directory
const isLocalPath =
this.source.startsWith('./') ||
this.source.startsWith('../') ||
this.source.startsWith('/') ||
this.source.startsWith('~') ||
this.source.includes('\\') ||
isAbsolute(this.source);
if (isLocalPath && existsSync(resolvedSource)) {
const targetDir = join(pluginsDir, pluginName);
// Verify targetDir is within pluginsDir (defense in depth)
const resolvedTarget = resolve(targetDir);
const resolvedPluginsDir = resolve(pluginsDir);
if (!resolvedTarget.startsWith(resolvedPluginsDir + sep)) {
this.context.stderr.write(chalk.red('Invalid plugin name\n'));
return 1;
}
// Create plugins directory if needed
if (!existsSync(pluginsDir)) {
mkdirSync(pluginsDir, { recursive: true });
}
// Copy plugin to plugins directory
const { statSync } = await import('node:fs');
const sourceStat = statSync(resolvedSource);
if (sourceStat.isDirectory()) {
// Copy entire directory
cpSync(resolvedSource, targetDir, { recursive: true });
} else {
// Copy single file with a loader-recognized name
if (!existsSync(targetDir)) {
mkdirSync(targetDir, { recursive: true });
}
// Preserve .mjs for ESM plugins, use .js for others
let destFileName: string;
if (resolvedSource.endsWith('.json')) {
destFileName = 'plugin.json';
} else if (resolvedSource.endsWith('.mjs')) {
destFileName = 'index.mjs';
} else {
destFileName = 'index.js';
}
copyFileSync(resolvedSource, join(targetDir, destFileName));
}
this.context.stdout.write(chalk.dim(` Copied to ${targetDir}\n`));
}
await pluginManager.register(plugin);
this.context.stdout.write(chalk.green(`✓ Plugin "${plugin.metadata.name}" installed!\n`));
this.context.stdout.write(` Version: ${plugin.metadata.version}\n`);
if (plugin.metadata.description) {
this.context.stdout.write(` ${plugin.metadata.description}\n`);
}
// Show what was registered
if (plugin.translators?.length) {
this.context.stdout.write(` Translators: ${plugin.translators.map((t) => t.agentType).join(', ')}\n`);
}
if (plugin.providers?.length) {
this.context.stdout.write(` Providers: ${plugin.providers.map((p) => p.providerName).join(', ')}\n`);
}
if (plugin.commands?.length) {
this.context.stdout.write(` Commands: ${plugin.commands.map((c) => c.name).join(', ')}\n`);
}
return 0;
}
private async uninstallPlugin(pluginManager: ReturnType<typeof createPluginManager>): Promise<number> {
if (!this.name) {
this.context.stderr.write(chalk.red('--name is required for uninstall\n'));
return 1;
}
// Validate plugin name to prevent path traversal attacks
if (!this.isValidPluginName(this.name)) {
this.context.stderr.write(chalk.red('Invalid plugin name\n'));
return 1;
}
await pluginManager.unregister(this.name);
// Remove plugin files from disk
const projectPath = this.global
? join(homedir(), '.skillkit')
: process.cwd();
const pluginsDir = this.global
? join(projectPath, 'plugins')
: join(projectPath, '.skillkit', 'plugins');
const pluginDir = join(pluginsDir, this.name);
// Verify pluginDir is within pluginsDir (defense in depth)
const resolvedPluginDir = resolve(pluginDir);
const resolvedPluginsDir = resolve(pluginsDir);
if (!resolvedPluginDir.startsWith(resolvedPluginsDir + sep)) {
this.context.stderr.write(chalk.red('Invalid plugin name\n'));
return 1;
}
if (existsSync(pluginDir)) {
rmSync(pluginDir, { recursive: true, force: true });
this.context.stdout.write(chalk.dim(` Removed ${pluginDir}\n`));
}
this.context.stdout.write(chalk.green(`✓ Plugin "${this.name}" uninstalled.\n`));
return 0;
}
private enablePlugin(pluginManager: ReturnType<typeof createPluginManager>): number {
if (!this.name) {
this.context.stderr.write(chalk.red('--name is required for enable\n'));
return 1;
}
pluginManager.enablePlugin(this.name);
this.context.stdout.write(chalk.green(`✓ Plugin "${this.name}" enabled.\n`));
return 0;
}
private disablePlugin(pluginManager: ReturnType<typeof createPluginManager>): number {
if (!this.name) {
this.context.stderr.write(chalk.red('--name is required for disable\n'));
return 1;
}
pluginManager.disablePlugin(this.name);
this.context.stdout.write(chalk.green(`✓ Plugin "${this.name}" disabled.\n`));
return 0;
}
private pluginInfo(pluginManager: ReturnType<typeof createPluginManager>): number {
if (!this.name) {
this.context.stderr.write(chalk.red('--name is required for info\n'));
return 1;
}
const plugin = pluginManager.getPlugin(this.name);
if (!plugin) {
this.context.stderr.write(chalk.red(`Plugin "${this.name}" not found.\n`));
return 1;
}
const { metadata } = plugin;
const enabled = pluginManager.isPluginEnabled(this.name);
this.context.stdout.write(chalk.cyan(`${metadata.name}`) + ` v${metadata.version}\n`);
this.context.stdout.write(`Status: ${enabled ? 'enabled' : 'disabled'}\n`);
if (metadata.description) {
this.context.stdout.write(`Description: ${metadata.description}\n`);
}
if (metadata.author) {
this.context.stdout.write(`Author: ${metadata.author}\n`);
}
if (metadata.homepage) {
this.context.stdout.write(`Homepage: ${metadata.homepage}\n`);
}
if (metadata.keywords?.length) {
this.context.stdout.write(`Keywords: ${metadata.keywords.join(', ')}\n`);
}
if (metadata.dependencies?.length) {
this.context.stdout.write(`Dependencies: ${metadata.dependencies.join(', ')}\n`);
}
return 0;
}
}
+66 -223
View File
@@ -1,19 +1,20 @@
import { Command, Option } from 'clipanion';
import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { resolve, join } from 'node:path';
import { resolve } from 'node:path';
import chalk from 'chalk';
import ora from 'ora';
import {
type ProjectProfile,
type SkillSummary,
type SkillIndex,
type ScoredSkill,
ContextManager,
RecommendationEngine,
buildSkillIndex,
saveIndex,
loadIndex as loadIndexFromCache,
isIndexStale,
INDEX_PATH,
KNOWN_SKILL_REPOS,
} from '@skillkit/core';
const INDEX_PATH = join(process.env.HOME || '~', '.skillkit', 'index.json');
const INDEX_CACHE_HOURS = 24;
/**
* Recommend command - get smart skill recommendations based on project analysis
*/
@@ -41,7 +42,8 @@ export class RecommendCommand extends Command {
['Filter by category', '$0 recommend --category security'],
['Show detailed reasons', '$0 recommend --verbose'],
['Update skill index', '$0 recommend --update'],
['Search for skills by task', '$0 recommend --search "authentication"'],
['Search for skills by task', '$0 recommend --task "authentication"'],
['Search for skills (alias)', '$0 recommend --search "testing"'],
],
});
@@ -70,11 +72,16 @@ export class RecommendCommand extends Command {
description: 'Update skill index from sources',
});
// Search mode
// Search mode (--search or --task)
search = Option.String('--search,-s', {
description: 'Search skills by task/query',
});
// Task alias for search (GSD-style)
task = Option.String('--task,-t', {
description: 'Search skills by task (alias for --search)',
});
// Include installed skills
includeInstalled = Option.Boolean('--include-installed', false, {
description: 'Include already installed skills',
@@ -95,7 +102,7 @@ export class RecommendCommand extends Command {
// Handle index update
if (this.update) {
return this.updateIndex();
return await this.updateIndex();
}
// Load or create project profile
@@ -121,9 +128,10 @@ export class RecommendCommand extends Command {
const engine = new RecommendationEngine();
engine.loadIndex(index);
// Handle search mode
if (this.search) {
return this.handleSearch(engine, this.search);
// Handle search mode (--search or --task)
const searchQuery = this.search || this.task;
if (searchQuery) {
return this.handleSearch(engine, searchQuery);
}
// Get recommendations
@@ -308,72 +316,65 @@ export class RecommendCommand extends Command {
/**
* Load skill index from cache
*/
private loadIndex(): SkillIndex | null {
if (!existsSync(INDEX_PATH)) {
private loadIndex() {
const index = loadIndexFromCache();
if (!index) {
return null;
}
try {
const content = readFileSync(INDEX_PATH, 'utf-8');
const index = JSON.parse(content) as SkillIndex;
// Check if index is stale
// Check if index is stale
if (isIndexStale(index) && !this.json) {
const lastUpdated = new Date(index.lastUpdated);
const hoursSinceUpdate = (Date.now() - lastUpdated.getTime()) / (1000 * 60 * 60);
if (hoursSinceUpdate > INDEX_CACHE_HOURS && !this.json) {
console.log(
chalk.dim(`Index is ${Math.round(hoursSinceUpdate)} hours old. Run --update to refresh.\n`)
);
}
return index;
} catch {
return null;
console.log(
chalk.dim(`Index is ${Math.round(hoursSinceUpdate)} hours old. Run --update to refresh.\n`)
);
}
return index;
}
/**
* Update skill index from sources
*/
private updateIndex(): number {
console.log(chalk.cyan('Updating skill index...\n'));
private async updateIndex(): Promise<number> {
console.log(chalk.cyan('Updating skill index from GitHub repositories...\n'));
console.log(chalk.dim(`Sources: ${KNOWN_SKILL_REPOS.map(r => `${r.owner}/${r.repo}`).join(', ')}\n`));
// For now, create a sample index with well-known skill repositories
// In the future, this would fetch from a registry or known skill sources
const sampleIndex: SkillIndex = {
version: 1,
lastUpdated: new Date().toISOString(),
skills: getSampleSkills(),
sources: [
{
name: 'vercel-labs',
url: 'https://github.com/vercel-labs/agent-skills',
lastFetched: new Date().toISOString(),
skillCount: 5,
},
{
name: 'anthropics',
url: 'https://github.com/anthropics/skills',
lastFetched: new Date().toISOString(),
skillCount: 3,
},
],
};
const spinner = ora('Fetching skills...').start();
// Save index
const indexDir = join(process.env.HOME || '~', '.skillkit');
if (!existsSync(indexDir)) {
mkdirSync(indexDir, { recursive: true });
try {
const { index, errors } = await buildSkillIndex(KNOWN_SKILL_REPOS, (message) => {
spinner.text = message;
});
spinner.stop();
// Report any errors
if (errors.length > 0) {
console.log(chalk.yellow('\nWarnings:'));
for (const error of errors) {
console.log(chalk.dim(` • ${error}`));
}
console.log();
}
// Save the index
saveIndex(index);
console.log(chalk.green(`✓ Updated index with ${index.skills.length} skills`));
if (index.sources.length > 0) {
console.log(chalk.dim(` Sources: ${index.sources.map((s) => s.name).join(', ')}`));
}
console.log(chalk.dim(` Saved to: ${INDEX_PATH}\n`));
return 0;
} catch (error) {
spinner.fail('Failed to update index');
console.error(chalk.red(error instanceof Error ? error.message : String(error)));
return 1;
}
writeFileSync(INDEX_PATH, JSON.stringify(sampleIndex, null, 2));
console.log(chalk.green(`✓ Updated index with ${sampleIndex.skills.length} skills`));
console.log(chalk.dim(` Sources: ${sampleIndex.sources.map((s) => s.name).join(', ')}`));
console.log(chalk.dim(` Saved to: ${INDEX_PATH}\n`));
return 0;
}
}
@@ -384,161 +385,3 @@ function truncate(str: string, maxLen: number): string {
if (str.length <= maxLen) return str;
return str.slice(0, maxLen - 3) + '...';
}
/**
* Sample skills for the index (in a real implementation, this would fetch from sources)
*/
function getSampleSkills(): SkillSummary[] {
return [
{
name: 'vercel-react-best-practices',
description: 'Modern React patterns including Server Components, hooks best practices, and performance optimization',
source: 'vercel-labs/agent-skills',
tags: ['react', 'frontend', 'typescript', 'nextjs', 'performance'],
compatibility: {
frameworks: ['react', 'nextjs'],
languages: ['typescript', 'javascript'],
libraries: [],
},
popularity: 1500,
quality: 95,
lastUpdated: new Date().toISOString(),
verified: true,
},
{
name: 'tailwind-v4-patterns',
description: 'Tailwind CSS v4 utility patterns, responsive design, and component styling best practices',
source: 'vercel-labs/agent-skills',
tags: ['tailwind', 'css', 'styling', 'frontend', 'responsive'],
compatibility: {
frameworks: [],
languages: ['typescript', 'javascript'],
libraries: ['tailwindcss'],
},
popularity: 1200,
quality: 92,
lastUpdated: new Date().toISOString(),
verified: true,
},
{
name: 'nextjs-app-router',
description: 'Next.js App Router patterns including layouts, server actions, and data fetching',
source: 'vercel-labs/agent-skills',
tags: ['nextjs', 'react', 'routing', 'server-actions', 'frontend'],
compatibility: {
frameworks: ['nextjs'],
languages: ['typescript', 'javascript'],
libraries: [],
},
popularity: 1100,
quality: 94,
lastUpdated: new Date().toISOString(),
verified: true,
},
{
name: 'typescript-strict-patterns',
description: 'TypeScript strict mode patterns, type safety, and advanced type utilities',
source: 'anthropics/skills',
tags: ['typescript', 'types', 'safety', 'patterns'],
compatibility: {
frameworks: [],
languages: ['typescript'],
libraries: [],
},
popularity: 900,
quality: 90,
lastUpdated: new Date().toISOString(),
verified: true,
},
{
name: 'supabase-best-practices',
description: 'Supabase integration patterns including auth, database queries, and real-time subscriptions',
source: 'anthropics/skills',
tags: ['supabase', 'database', 'auth', 'backend', 'postgresql'],
compatibility: {
frameworks: [],
languages: ['typescript', 'javascript'],
libraries: ['@supabase/supabase-js'],
},
popularity: 800,
quality: 88,
lastUpdated: new Date().toISOString(),
verified: true,
},
{
name: 'vitest-testing-patterns',
description: 'Testing patterns with Vitest including mocking, assertions, and test organization',
source: 'anthropics/skills',
tags: ['vitest', 'testing', 'typescript', 'mocking', 'tdd'],
compatibility: {
frameworks: [],
languages: ['typescript', 'javascript'],
libraries: ['vitest'],
},
popularity: 700,
quality: 86,
lastUpdated: new Date().toISOString(),
verified: false,
},
{
name: 'prisma-database-patterns',
description: 'Prisma ORM patterns for schema design, migrations, and efficient queries',
source: 'vercel-labs/agent-skills',
tags: ['prisma', 'database', 'orm', 'postgresql', 'backend'],
compatibility: {
frameworks: [],
languages: ['typescript'],
libraries: ['@prisma/client'],
},
popularity: 850,
quality: 89,
lastUpdated: new Date().toISOString(),
verified: true,
},
{
name: 'security-best-practices',
description: 'Security patterns for web applications including XSS prevention, CSRF, and secure headers',
source: 'trailofbits/skills',
tags: ['security', 'xss', 'csrf', 'headers', 'owasp'],
compatibility: {
frameworks: [],
languages: ['typescript', 'javascript', 'python'],
libraries: [],
},
popularity: 600,
quality: 95,
lastUpdated: new Date().toISOString(),
verified: true,
},
{
name: 'python-fastapi-patterns',
description: 'FastAPI best practices for building high-performance Python APIs',
source: 'python-skills/fastapi',
tags: ['python', 'fastapi', 'backend', 'api', 'async'],
compatibility: {
frameworks: ['fastapi'],
languages: ['python'],
libraries: [],
},
popularity: 550,
quality: 85,
lastUpdated: new Date().toISOString(),
verified: false,
},
{
name: 'zustand-state-management',
description: 'Zustand state management patterns for React applications',
source: 'react-skills/state',
tags: ['zustand', 'react', 'state-management', 'frontend'],
compatibility: {
frameworks: ['react'],
languages: ['typescript', 'javascript'],
libraries: ['zustand'],
},
popularity: 650,
quality: 84,
lastUpdated: new Date().toISOString(),
verified: false,
},
];
}
+83
View File
@@ -0,0 +1,83 @@
import { Command, Option } from 'clipanion';
import { resolve } from 'node:path';
import chalk from 'chalk';
import { SessionManager } from '@skillkit/core';
/**
* Resume command - resume paused skill execution
*/
export class ResumeCommand extends Command {
static override paths = [['resume']];
static override usage = Command.Usage({
description: 'Resume a paused skill execution',
details: `
The resume command continues a previously paused skill execution
from where it left off.
The execution state is preserved, including:
- Completed tasks
- User decisions
- Modified files
`,
examples: [
['Resume paused execution', '$0 resume'],
],
});
// Project path
projectPath = Option.String('--path,-p', {
description: 'Project path (default: current directory)',
});
async execute(): Promise<number> {
const targetPath = resolve(this.projectPath || process.cwd());
const manager = new SessionManager(targetPath);
const state = manager.get();
if (!state) {
console.log(chalk.yellow('No active session found.'));
return 1;
}
if (!state.currentExecution) {
console.log(chalk.yellow('No skill execution to resume.'));
console.log(chalk.dim('Start a new execution with: skillkit run <skill>'));
return 1;
}
if (state.currentExecution.status !== 'paused') {
if (state.currentExecution.status === 'running') {
console.log(chalk.yellow('Execution is already running.'));
} else {
console.log(chalk.yellow(`Execution is ${state.currentExecution.status}.`));
}
return 1;
}
const success = manager.resume();
if (success) {
const exec = state.currentExecution;
console.log(chalk.green('✓ Execution resumed'));
console.log();
console.log(` Skill: ${chalk.bold(exec.skillName)}`);
console.log(` Progress: ${exec.currentStep}/${exec.totalSteps} tasks`);
console.log();
// Show next task
const nextTask = exec.tasks.find((t) => t.status === 'pending' || t.status === 'in_progress');
if (nextTask) {
console.log(` Next task: ${chalk.cyan(nextTask.name)}`);
}
console.log();
console.log(chalk.dim('The execution will continue from where it left off.'));
console.log(chalk.dim('View status: skillkit status'));
return 0;
} else {
console.log(chalk.red('Failed to resume execution.'));
return 1;
}
}
}
+336
View File
@@ -0,0 +1,336 @@
import { Command, Option } from 'clipanion';
import { resolve, join } from 'node:path';
import { existsSync, readFileSync, statSync } from 'node:fs';
import chalk from 'chalk';
import ora from 'ora';
import {
createExecutionEngine,
discoverSkills,
extractFrontmatter,
type ExecutableSkill,
type ExecutableTask,
type AgentType,
} from '@skillkit/core';
/**
* Run command - execute a skill
*/
export class RunCommand extends Command {
static override paths = [['run']];
static override usage = Command.Usage({
description: 'Execute a skill with task-based orchestration',
details: `
The run command executes a skill, optionally breaking it down into
tasks with verification checkpoints.
Skills can be:
- Installed skills (by name)
- Local skill files (by path)
- Remote skills (owner/repo/path)
`,
examples: [
['Run an installed skill', '$0 run typescript-strict-mode'],
['Run a local skill file', '$0 run ./my-skill/SKILL.md'],
['Dry run (show what would happen)', '$0 run typescript-strict-mode --dry-run'],
['Run with verification', '$0 run setup-testing --verify'],
],
});
// Skill name or path
skillRef = Option.String({ required: true });
// Target agent
agent = Option.String('--agent,-a', {
description: 'Target agent (claude-code, cursor, etc.)',
});
// Dry run
dryRun = Option.Boolean('--dry-run,-n', false, {
description: 'Show what would be executed without running',
});
// Enable verification
verify = Option.Boolean('--verify', false, {
description: 'Run verification checks after each task',
});
// Auto-commit
autoCommit = Option.Boolean('--auto-commit', false, {
description: 'Create git commits after each task',
});
// Continue on error
continueOnError = Option.Boolean('--continue-on-error', false, {
description: 'Continue execution even if a task fails',
});
// Verbose output
verbose = Option.Boolean('--verbose,-v', false, {
description: 'Show detailed execution progress',
});
// JSON output
json = Option.Boolean('--json,-j', false, {
description: 'Output in JSON format',
});
// Project path
projectPath = Option.String('--path,-p', {
description: 'Project path (default: current directory)',
});
async execute(): Promise<number> {
const targetPath = resolve(this.projectPath || process.cwd());
// Load the skill
const skill = await this.loadSkill(targetPath);
if (!skill) {
return 1;
}
// Show skill info
if (!this.json) {
console.log(chalk.cyan(`Executing skill: ${chalk.bold(skill.name)}`));
if (skill.description) {
console.log(chalk.dim(skill.description));
}
console.log();
}
// Dry run mode
if (this.dryRun) {
this.showDryRun(skill);
return 0;
}
const spinner = ora();
let currentTask = '';
// Create execution engine
const engine = createExecutionEngine(targetPath, {
onProgress: (event) => {
if (this.json) return;
switch (event.type) {
case 'task_start':
currentTask = event.taskName || '';
spinner.start(`Task ${(event.taskIndex || 0) + 1}/${event.totalTasks}: ${currentTask}`);
break;
case 'task_complete':
const icon = event.status === 'completed' ? chalk.green('✓') : chalk.red('✗');
spinner.stopAndPersist({
symbol: icon,
text: `Task ${(event.taskIndex || 0) + 1}/${event.totalTasks}: ${currentTask}`,
});
if (event.error && this.verbose) {
console.log(chalk.red(` Error: ${event.error}`));
}
break;
case 'checkpoint':
spinner.info(`Checkpoint: ${event.message}`);
break;
case 'verification':
if (this.verbose) {
console.log(chalk.dim(` ${event.message}`));
}
break;
case 'complete':
console.log();
if (event.status === 'completed') {
console.log(chalk.green('✓ Skill execution completed'));
} else {
console.log(chalk.red(`✗ Skill execution ${event.status}`));
if (event.error) {
console.log(chalk.red(` Error: ${event.error}`));
}
}
break;
}
},
checkpointHandler: async (task, _context) => {
// For CLI, we auto-continue but could add interactive prompts
if (task.type === 'checkpoint:decision' && task.options) {
// Use first option by default
return {
continue: true,
selectedOption: task.options[0],
};
}
return { continue: true };
},
});
// Execute the skill
const result = await engine.execute(skill, {
agent: this.agent as AgentType | undefined,
autoCommit: this.autoCommit,
verify: this.verify,
continueOnError: this.continueOnError,
});
if (this.json) {
console.log(JSON.stringify(result, null, 2));
} else {
// Show summary
console.log();
console.log(chalk.cyan('Summary:'));
console.log(` Duration: ${chalk.dim(this.formatDuration(result.durationMs || 0))}`);
console.log(` Tasks: ${chalk.dim(`${result.tasks.filter(t => t.status === 'completed').length}/${result.tasks.length} completed`)}`);
if (result.filesModified.length > 0) {
console.log(` Files modified: ${chalk.dim(result.filesModified.length.toString())}`);
}
if (result.commits.length > 0) {
console.log(` Commits: ${chalk.dim(result.commits.join(', '))}`);
}
}
return result.status === 'completed' ? 0 : 1;
}
private async loadSkill(projectPath: string): Promise<ExecutableSkill | null> {
// Check if it's a file path (must be a file, not directory)
if (this.skillRef.endsWith('.md') || (existsSync(this.skillRef) && statSync(this.skillRef).isFile())) {
return this.loadSkillFromFile(resolve(this.skillRef));
}
// Check installed skills
const skill = this.findInstalledSkill(projectPath, this.skillRef);
if (skill) {
return skill;
}
console.error(chalk.red(`Skill "${this.skillRef}" not found`));
console.log(chalk.dim('Install skills with: skillkit install <source>'));
return null;
}
private loadSkillFromFile(filePath: string): ExecutableSkill | null {
if (!existsSync(filePath)) {
console.error(chalk.red(`File not found: ${filePath}`));
return null;
}
try {
const content = readFileSync(filePath, 'utf-8');
const frontmatter = extractFrontmatter(content);
// Parse tasks from frontmatter if present
const tasks = this.parseTasksFromFrontmatter(frontmatter);
return {
name: (frontmatter?.name as string) || this.skillRef,
description: frontmatter?.description as string,
version: frontmatter?.version as string,
source: filePath,
content,
tasks,
};
} catch (error) {
console.error(chalk.red(`Failed to load skill: ${error}`));
return null;
}
}
private findInstalledSkill(projectPath: string, skillName: string): ExecutableSkill | null {
// Search in common skill directories
const skillDirs = [
join(projectPath, '.claude', 'skills'),
join(projectPath, '.cursor', 'skills'),
join(projectPath, 'skills'),
join(projectPath, '.skillkit', 'skills'),
];
for (const dir of skillDirs) {
if (!existsSync(dir)) continue;
const skills = discoverSkills(dir);
const skill = skills.find((s) => s.name === skillName);
if (skill) {
const skillMdPath = join(skill.path, 'SKILL.md');
if (existsSync(skillMdPath)) {
return this.loadSkillFromFile(skillMdPath);
}
}
}
return null;
}
private parseTasksFromFrontmatter(frontmatter: Record<string, unknown> | null): ExecutableTask[] | undefined {
if (!frontmatter?.tasks || !Array.isArray(frontmatter.tasks)) {
return undefined;
}
return frontmatter.tasks.map((task: Record<string, unknown>, index: number) => ({
id: (task.id as string) || `task-${index}`,
name: (task.name as string) || `Task ${index + 1}`,
type: (task.type as ExecutableTask['type']) || 'auto',
action: (task.action as string) || '',
files: task.files as string[] | undefined,
options: task.options as string[] | undefined,
verify: task.verify as ExecutableTask['verify'],
}));
}
private showDryRun(skill: ExecutableSkill): void {
console.log(chalk.cyan('Dry Run - Execution Plan'));
console.log();
console.log(`Skill: ${chalk.bold(skill.name)}`);
if (skill.description) {
console.log(`Description: ${chalk.dim(skill.description)}`);
}
console.log(`Source: ${chalk.dim(skill.source)}`);
console.log();
if (skill.tasks && skill.tasks.length > 0) {
console.log(chalk.cyan('Tasks:'));
for (let i = 0; i < skill.tasks.length; i++) {
const task = skill.tasks[i];
const typeLabel = this.getTaskTypeLabel(task.type);
console.log(` ${i + 1}. ${task.name} ${typeLabel}`);
if (task.action) {
console.log(` ${chalk.dim(task.action)}`);
}
if (task.files && task.files.length > 0) {
console.log(` Files: ${chalk.dim(task.files.join(', '))}`);
}
}
} else {
console.log(chalk.dim('No structured tasks defined. Skill will be executed as a single unit.'));
}
console.log();
console.log(chalk.dim('This is a dry run. Remove --dry-run to execute.'));
}
private getTaskTypeLabel(type: string): string {
switch (type) {
case 'auto':
return chalk.green('[auto]');
case 'checkpoint:human-verify':
return chalk.yellow('[verify]');
case 'checkpoint:decision':
return chalk.blue('[decision]');
case 'checkpoint:human-action':
return chalk.magenta('[manual]');
default:
return '';
}
}
private formatDuration(ms: number): string {
if (ms < 1000) return `${ms}ms`;
if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
const minutes = Math.floor(ms / 60000);
const seconds = Math.floor((ms % 60000) / 1000);
return `${minutes}m ${seconds}s`;
}
}
+228
View File
@@ -0,0 +1,228 @@
import { Command, Option } from 'clipanion';
import chalk from 'chalk';
import { loadConfig, saveConfig, type SkillkitConfig, type AgentType } from '@skillkit/core';
const VALID_AGENTS: AgentType[] = [
'claude-code', 'cursor', 'codex', 'gemini-cli', 'opencode',
'antigravity', 'amp', 'clawdbot', 'droid', 'github-copilot',
'goose', 'kilo', 'kiro-cli', 'roo', 'trae', 'windsurf', 'universal',
];
/**
* Settings command - view and modify SkillKit configuration
*/
export class SettingsCommand extends Command {
static override paths = [['settings'], ['config']];
static override usage = Command.Usage({
description: 'View and modify SkillKit settings',
details: `
View or modify SkillKit configuration. Settings are stored in skillkit.yaml.
Without arguments, shows all current settings.
With --set, modifies a specific setting.
`,
examples: [
['Show all settings', '$0 settings'],
['Set default agent', '$0 settings --set agent=claude-code'],
['Enable auto-sync', '$0 settings --set autoSync=true'],
['Set cache directory', '$0 settings --set cacheDir=~/.cache/skillkit'],
['Show settings as JSON', '$0 settings --json'],
['Save to global config', '$0 settings --set agent=cursor --global'],
],
});
// Set a setting
set = Option.String('--set,-s', {
description: 'Set a config value (key=value)',
});
// Get a specific setting
get = Option.String('--get,-g', {
description: 'Get a specific setting value',
});
// JSON output
json = Option.Boolean('--json,-j', false, {
description: 'Output as JSON',
});
// Global config
global = Option.Boolean('--global', false, {
description: 'Use global config (~/.config/skillkit/)',
});
// Reset to defaults
reset = Option.Boolean('--reset', false, {
description: 'Reset all settings to defaults',
});
async execute(): Promise<number> {
// Load current config (respect --global flag)
const config = loadConfig(this.global);
// Reset to defaults
if (this.reset) {
const defaultConfig: SkillkitConfig = {
version: 1,
agent: 'universal',
autoSync: true,
};
saveConfig(defaultConfig, this.global);
console.log(chalk.green('Settings reset to defaults'));
return 0;
}
// Get a specific setting
if (this.get) {
// Check if the key is a known setting (not just if value is undefined)
const knownKeys = [
'agent', 'autoSync', 'cacheDir', 'skillsDir',
'enabledSkills', 'disabledSkills', 'marketplaceSources', 'defaultTimeout'
];
if (!knownKeys.includes(this.get)) {
console.error(chalk.red(`Unknown setting: ${this.get}`));
return 1;
}
const value = this.getConfigValue(config, this.get);
if (this.json) {
// Use null instead of undefined so the key is preserved in JSON output
console.log(JSON.stringify({ [this.get]: value ?? null }));
} else {
console.log(value ?? '(not set)');
}
return 0;
}
// Set a setting
if (this.set) {
const [key, ...valueParts] = this.set.split('=');
const value = valueParts.join('=');
if (!key || !this.set.includes('=')) {
console.error(chalk.red('Invalid format. Use: --set key=value'));
return 1;
}
const result = this.setConfigValue(config, key, value);
if (!result.success) {
console.error(chalk.red(result.error));
return 1;
}
saveConfig(config, this.global);
console.log(chalk.green(`${key} = ${value}`));
return 0;
}
// Show all settings
if (this.json) {
console.log(JSON.stringify(config, null, 2));
} else {
console.log(chalk.cyan('SkillKit Settings'));
console.log(chalk.dim('─'.repeat(40)));
console.log();
const settings = [
{ key: 'agent', label: 'Default Agent', value: config.agent },
{ key: 'autoSync', label: 'Auto Sync', value: config.autoSync ? 'enabled' : 'disabled' },
{ key: 'cacheDir', label: 'Cache Dir', value: config.cacheDir || '~/.skillkit/cache' },
{ key: 'skillsDir', label: 'Skills Dir', value: config.skillsDir || '(default)' },
{ key: 'defaultTimeout', label: 'Timeout', value: config.defaultTimeout ? `${config.defaultTimeout}ms` : '(default)' },
];
for (const setting of settings) {
console.log(` ${chalk.white(setting.label.padEnd(14))} ${chalk.dim(setting.value)}`);
}
if (config.enabledSkills?.length) {
console.log();
console.log(` ${chalk.white('Enabled Skills'.padEnd(14))} ${chalk.dim(config.enabledSkills.join(', '))}`);
}
if (config.disabledSkills?.length) {
console.log(` ${chalk.white('Disabled Skills'.padEnd(14))} ${chalk.dim(config.disabledSkills.join(', '))}`);
}
if (config.marketplaceSources?.length) {
console.log(` ${chalk.white('Marketplaces'.padEnd(14))} ${chalk.dim(config.marketplaceSources.join(', '))}`);
}
console.log();
console.log(chalk.dim('Use --set key=value to modify settings'));
console.log(chalk.dim('Available keys: agent, autoSync, cacheDir, skillsDir, defaultTimeout'));
}
return 0;
}
private getConfigValue(config: SkillkitConfig, key: string): unknown {
switch (key) {
case 'agent':
return config.agent;
case 'autoSync':
return config.autoSync;
case 'cacheDir':
return config.cacheDir;
case 'skillsDir':
return config.skillsDir;
case 'enabledSkills':
return config.enabledSkills;
case 'disabledSkills':
return config.disabledSkills;
case 'marketplaceSources':
return config.marketplaceSources;
case 'defaultTimeout':
return config.defaultTimeout;
default:
return undefined;
}
}
private setConfigValue(
config: SkillkitConfig,
key: string,
value: string
): { success: boolean; error?: string } {
switch (key) {
case 'agent':
if (!VALID_AGENTS.includes(value as AgentType)) {
return {
success: false,
error: `Invalid agent. Valid options: ${VALID_AGENTS.join(', ')}`,
};
}
config.agent = value as AgentType;
break;
case 'autoSync':
if (!['true', 'false', 'enabled', 'disabled'].includes(value.toLowerCase())) {
return { success: false, error: 'autoSync must be true/false or enabled/disabled' };
}
config.autoSync = value.toLowerCase() === 'true' || value.toLowerCase() === 'enabled';
break;
case 'cacheDir':
config.cacheDir = value || undefined;
break;
case 'skillsDir':
config.skillsDir = value || undefined;
break;
case 'defaultTimeout': {
const timeout = parseInt(value, 10);
if (isNaN(timeout) || timeout <= 0) {
return { success: false, error: 'defaultTimeout must be a positive number (milliseconds)' };
}
config.defaultTimeout = timeout;
break;
}
default:
return { success: false, error: `Unknown setting: ${key}` };
}
return { success: true };
}
}
+174
View File
@@ -0,0 +1,174 @@
import { Command, Option } from 'clipanion';
import { resolve } from 'node:path';
import chalk from 'chalk';
import { SessionManager } from '@skillkit/core';
/**
* Status command - show current session state
*/
export class StatusCommand extends Command {
static override paths = [['status'], ['st']];
static override usage = Command.Usage({
description: 'Show current session state and execution progress',
details: `
The status command shows the current state of skill execution sessions,
including any paused executions and recent history.
`,
examples: [
['Show session status', '$0 status'],
['Show with history', '$0 status --history'],
['Show JSON output', '$0 status --json'],
],
});
// Show history
history = Option.Boolean('--history,-h', false, {
description: 'Show execution history',
});
// History limit
limit = Option.String('--limit,-l', {
description: 'Limit history entries (default: 10)',
});
// JSON output
json = Option.Boolean('--json,-j', false, {
description: 'Output in JSON format',
});
// Project path
projectPath = Option.String('--path,-p', {
description: 'Project path (default: current directory)',
});
async execute(): Promise<number> {
const targetPath = resolve(this.projectPath || process.cwd());
const manager = new SessionManager(targetPath);
const state = manager.get();
if (this.json) {
console.log(JSON.stringify(state || { message: 'No session found' }, null, 2));
return 0;
}
if (!state) {
console.log(chalk.dim('No active session found.'));
console.log(chalk.dim('Run a skill with "skillkit run <skill>" to start a session.'));
return 0;
}
// Show current execution
if (state.currentExecution) {
const exec = state.currentExecution;
const statusColor = exec.status === 'paused' ? chalk.yellow : chalk.green;
console.log(chalk.cyan('Current Execution:\n'));
console.log(` Skill: ${chalk.bold(exec.skillName)}`);
console.log(` Source: ${chalk.dim(exec.skillSource)}`);
console.log(` Status: ${statusColor(exec.status)}`);
console.log(` Progress: ${exec.currentStep}/${exec.totalSteps} tasks`);
console.log(` Started: ${chalk.dim(new Date(exec.startedAt).toLocaleString())}`);
if (exec.pausedAt) {
console.log(` Paused: ${chalk.dim(new Date(exec.pausedAt).toLocaleString())}`);
}
console.log(chalk.cyan('\n Tasks:'));
for (const task of exec.tasks) {
const statusIcon = this.getStatusIcon(task.status);
const statusText = this.getStatusColor(task.status)(task.status);
console.log(` ${statusIcon} ${task.name} - ${statusText}`);
if (task.error) {
console.log(` ${chalk.red('Error:')} ${task.error}`);
}
}
if (exec.status === 'paused') {
console.log(chalk.yellow('\n Resume with: skillkit resume'));
}
} else {
console.log(chalk.dim('No active execution.'));
}
// Show history
if (this.history || (!state.currentExecution && state.history.length > 0)) {
const limit = this.limit ? parseInt(this.limit, 10) : 10;
const history = manager.getHistory(limit);
if (history.length > 0) {
console.log(chalk.cyan('\nExecution History:\n'));
for (const entry of history) {
const statusColor = entry.status === 'completed' ? chalk.green : chalk.red;
const duration = this.formatDuration(entry.durationMs);
console.log(` ${statusColor('●')} ${chalk.bold(entry.skillName)}`);
console.log(` ${chalk.dim(entry.skillSource)} • ${duration}`);
console.log(` ${chalk.dim(new Date(entry.completedAt).toLocaleString())}`);
if (entry.commits.length > 0) {
console.log(` Commits: ${chalk.dim(entry.commits.join(', '))}`);
}
if (entry.error) {
console.log(` ${chalk.red('Error:')} ${entry.error}`);
}
console.log();
}
}
}
// Show decisions
if (state.decisions.length > 0) {
console.log(chalk.cyan('Saved Decisions:\n'));
for (const decision of state.decisions.slice(0, 5)) {
console.log(` ${chalk.dim(decision.key)}: ${decision.value}`);
}
if (state.decisions.length > 5) {
console.log(chalk.dim(` ... and ${state.decisions.length - 5} more`));
}
}
return 0;
}
private getStatusIcon(status: string): string {
switch (status) {
case 'completed':
return chalk.green('✓');
case 'failed':
return chalk.red('✗');
case 'in_progress':
return chalk.blue('●');
case 'paused':
return chalk.yellow('⏸');
default:
return chalk.dim('○');
}
}
private getStatusColor(status: string): (text: string) => string {
switch (status) {
case 'completed':
return chalk.green;
case 'failed':
return chalk.red;
case 'in_progress':
return chalk.blue;
case 'paused':
return chalk.yellow;
default:
return chalk.dim;
}
}
private formatDuration(ms: number): string {
if (ms < 1000) return `${ms}ms`;
if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
const minutes = Math.floor(ms / 60000);
const seconds = Math.floor((ms % 60000) / 1000);
return `${minutes}m ${seconds}s`;
}
}
+360
View File
@@ -0,0 +1,360 @@
/**
* Team Command
*
* Manage team skill sharing and collaboration
*/
import { Command, Option } from 'clipanion';
import chalk from 'chalk';
import { createTeamManager, createSkillBundle, exportBundle, importBundle } from '@skillkit/core';
import { join } from 'node:path';
export class TeamCommand extends Command {
static override paths = [['team']];
static override usage = Command.Usage({
description: 'Manage team skill sharing and collaboration',
examples: [
['Initialize team', '$0 team init --name "My Team" --registry https://github.com/myteam/skills'],
['Share a skill', '$0 team share --name my-skill'],
['Import a skill', '$0 team import --name shared-skill'],
['List shared skills', '$0 team list'],
['Sync with remote', '$0 team sync'],
['Create a bundle', '$0 team bundle-create --name my-bundle --skills skill1,skill2'],
['Export a bundle', '$0 team bundle-export --name my-bundle --output ./bundle.json'],
['Import a bundle', '$0 team bundle-import --source ./bundle.json'],
],
});
action = Option.String({ required: true });
name = Option.String('--name', { description: 'Team name (for init), skill name, or bundle name' });
registry = Option.String('--registry', { description: 'Registry URL (for init)' });
description = Option.String('--description,-d', { description: 'Description (for share/bundle)' });
tags = Option.String('--tags,-t', { description: 'Comma-separated tags (for share)' });
skills = Option.String('--skills', { description: 'Comma-separated skill names (for bundle)' });
output = Option.String('--output,-o', { description: 'Output path (for bundle-export)' });
source = Option.String('--source,-s', { description: 'Source path (for bundle-import)' });
overwrite = Option.Boolean('--overwrite', { description: 'Overwrite existing (for import)' });
dryRun = Option.Boolean('--dry-run', { description: 'Preview without changes' });
async execute(): Promise<number> {
const projectPath = process.cwd();
const teamManager = createTeamManager(projectPath);
try {
switch (this.action) {
case 'init':
return await this.initTeam(teamManager);
case 'share':
return await this.shareSkill(teamManager);
case 'import':
return await this.importSkill(teamManager);
case 'list':
return await this.listSkills(teamManager);
case 'sync':
return await this.syncTeam(teamManager);
case 'remove':
return await this.removeSkill(teamManager);
case 'bundle-create':
return await this.createBundle(teamManager);
case 'bundle-export':
return await this.exportSkillBundle(teamManager);
case 'bundle-import':
return await this.importSkillBundle();
default:
this.context.stderr.write(chalk.red(`Unknown action: ${this.action}\n`));
this.context.stderr.write('Available actions: init, share, import, list, sync, remove, bundle-create, bundle-export, bundle-import\n');
return 1;
}
} catch (err) {
this.context.stderr.write(chalk.red(`✗ ${err instanceof Error ? err.message : 'Unknown error'}\n`));
return 1;
}
}
private async initTeam(teamManager: ReturnType<typeof createTeamManager>): Promise<number> {
if (!this.name) {
this.context.stderr.write(chalk.red('--name is required for init\n'));
return 1;
}
if (!this.registry) {
this.context.stderr.write(chalk.red('--registry is required for init\n'));
return 1;
}
const config = await teamManager.init({
teamName: this.name,
registryUrl: this.registry,
});
this.context.stdout.write(chalk.green('✓ Team initialized!\n'));
this.context.stdout.write(` Team ID: ${config.teamId}\n`);
this.context.stdout.write(` Registry: ${config.registryUrl}\n`);
return 0;
}
private async shareSkill(teamManager: ReturnType<typeof createTeamManager>): Promise<number> {
const config = teamManager.load();
if (!config) {
this.context.stderr.write(chalk.red('Team not initialized. Run `skillkit team init` first.\n'));
return 1;
}
if (!this.name) {
this.context.stderr.write(chalk.red('--name <skill-name> is required for share\n'));
return 1;
}
const shared = await teamManager.shareSkill({
skillName: this.name,
description: this.description,
tags: this.tags?.split(',').map((t) => t.trim()),
});
this.context.stdout.write(chalk.green('✓ Skill shared!\n'));
this.context.stdout.write(` Name: ${shared.name}\n`);
this.context.stdout.write(` Version: ${shared.version}\n`);
this.context.stdout.write(` Source: ${shared.source}\n`);
return 0;
}
private async importSkill(teamManager: ReturnType<typeof createTeamManager>): Promise<number> {
const config = teamManager.load();
if (!config) {
this.context.stderr.write(chalk.red('Team not initialized. Run `skillkit team init` first.\n'));
return 1;
}
if (!this.name) {
this.context.stderr.write(chalk.red('--name <skill-name> is required for import\n'));
return 1;
}
const result = await teamManager.importSkill(this.name, {
overwrite: this.overwrite,
dryRun: this.dryRun,
});
if (!result.success) {
this.context.stderr.write(chalk.red(`✗ ${result.error}\n`));
return 1;
}
if (this.dryRun) {
this.context.stdout.write(chalk.cyan(`[dry-run] Would import to: ${result.path}\n`));
} else {
this.context.stdout.write(chalk.green(`✓ Skill imported to: ${result.path}\n`));
}
return 0;
}
private async listSkills(teamManager: ReturnType<typeof createTeamManager>): Promise<number> {
const config = teamManager.load();
if (!config) {
this.context.stderr.write(chalk.red('Team not initialized. Run `skillkit team init` first.\n'));
return 1;
}
const skills = teamManager.listSharedSkills();
this.context.stdout.write(chalk.cyan(`Team: ${config.teamName}\n`));
this.context.stdout.write(chalk.gray(`Registry: ${config.registryUrl}\n\n`));
if (skills.length === 0) {
this.context.stdout.write('No shared skills yet. Use `skillkit team share` to share a skill.\n');
return 0;
}
this.context.stdout.write(`Shared Skills (${skills.length}):\n`);
for (const skill of skills) {
this.context.stdout.write(chalk.cyan(` ${skill.name}`) + ` v${skill.version}\n`);
if (skill.description) {
this.context.stdout.write(chalk.gray(` ${skill.description}\n`));
}
this.context.stdout.write(` by ${skill.author} | ${skill.downloads || 0} downloads\n`);
}
return 0;
}
private async syncTeam(teamManager: ReturnType<typeof createTeamManager>): Promise<number> {
const config = teamManager.load();
if (!config) {
this.context.stderr.write(chalk.red('Team not initialized. Run `skillkit team init` first.\n'));
return 1;
}
this.context.stdout.write(`Syncing with ${config.registryUrl}...\n`);
const result = await teamManager.sync();
this.context.stdout.write(chalk.green('✓ Sync complete!\n'));
if (result.added.length > 0) {
this.context.stdout.write(` Added: ${result.added.join(', ')}\n`);
}
if (result.updated.length > 0) {
this.context.stdout.write(` Updated: ${result.updated.join(', ')}\n`);
}
if (result.added.length === 0 && result.updated.length === 0) {
this.context.stdout.write(' Already up to date.\n');
}
return 0;
}
private async removeSkill(teamManager: ReturnType<typeof createTeamManager>): Promise<number> {
const config = teamManager.load();
if (!config) {
this.context.stderr.write(chalk.red('Team not initialized. Run `skillkit team init` first.\n'));
return 1;
}
if (!this.name) {
this.context.stderr.write(chalk.red('--name <skill-name> is required for remove\n'));
return 1;
}
const removed = teamManager.removeSkill(this.name);
if (!removed) {
this.context.stderr.write(chalk.red(`Skill "${this.name}" not found in team registry.\n`));
return 1;
}
this.context.stdout.write(chalk.green(`✓ Skill "${this.name}" removed from team registry.\n`));
return 0;
}
private async createBundle(teamManager: ReturnType<typeof createTeamManager>): Promise<number> {
const config = teamManager.load();
if (!config) {
this.context.stderr.write(chalk.red('Team not initialized. Run `skillkit team init` first.\n'));
return 1;
}
if (!this.name) {
this.context.stderr.write(chalk.red('--name <bundle-name> is required for bundle-create\n'));
return 1;
}
if (!this.skills) {
this.context.stderr.write(chalk.red('--skills <skill1,skill2,...> is required for bundle-create\n'));
return 1;
}
const skillNames = this.skills.split(',').map((s) => s.trim());
const projectPath = process.cwd();
const skillsDir = join(projectPath, 'skills');
// Create the bundle
const bundle = createSkillBundle(this.name, config.teamName, this.description);
let addedCount = 0;
for (const skillName of skillNames) {
const skillPath = join(skillsDir, skillName);
try {
bundle.addSkill(skillPath);
addedCount++;
this.context.stdout.write(chalk.gray(` + ${skillName}\n`));
} catch (err) {
this.context.stderr.write(chalk.yellow(` ⚠ Skipping ${skillName}: ${err instanceof Error ? err.message : 'Unknown error'}\n`));
}
}
if (addedCount === 0) {
this.context.stderr.write(chalk.red('No skills were added to the bundle.\n'));
return 1;
}
// Export to default location
const outputPath = this.output || join(projectPath, '.skillkit', 'bundles', `${this.name}.json`);
const result = exportBundle(bundle, outputPath);
if (!result.success) {
this.context.stderr.write(chalk.red(`✗ ${result.error}\n`));
return 1;
}
this.context.stdout.write(chalk.green(`\n✓ Bundle "${this.name}" created with ${addedCount} skills!\n`));
this.context.stdout.write(` Checksum: ${bundle.getChecksum()}\n`);
this.context.stdout.write(` Output: ${result.path}\n`);
return 0;
}
private async exportSkillBundle(teamManager: ReturnType<typeof createTeamManager>): Promise<number> {
const config = teamManager.load();
if (!config) {
this.context.stderr.write(chalk.red('Team not initialized. Run `skillkit team init` first.\n'));
return 1;
}
if (!this.name) {
this.context.stderr.write(chalk.red('--name <bundle-name> is required for bundle-export\n'));
return 1;
}
if (!this.output) {
this.context.stderr.write(chalk.red('--output <path> is required for bundle-export\n'));
return 1;
}
const projectPath = process.cwd();
const bundlePath = join(projectPath, '.skillkit', 'bundles', `${this.name}.json`);
// Check if bundle exists
const { existsSync, readFileSync, writeFileSync } = await import('node:fs');
if (!existsSync(bundlePath)) {
this.context.stderr.write(chalk.red(`Bundle "${this.name}" not found. Create it first with bundle-create.\n`));
return 1;
}
// Copy bundle to output
const content = readFileSync(bundlePath, 'utf-8');
writeFileSync(this.output, content, 'utf-8');
this.context.stdout.write(chalk.green(`✓ Bundle exported to: ${this.output}\n`));
return 0;
}
private async importSkillBundle(): Promise<number> {
if (!this.source) {
this.context.stderr.write(chalk.red('--source <path> is required for bundle-import\n'));
return 1;
}
const { existsSync } = await import('node:fs');
if (!existsSync(this.source)) {
this.context.stderr.write(chalk.red(`Bundle file not found: ${this.source}\n`));
return 1;
}
const projectPath = process.cwd();
const skillsDir = join(projectPath, 'skills');
if (this.dryRun) {
this.context.stdout.write(chalk.cyan('[dry-run] Would import bundle to: ' + skillsDir + '\n'));
return 0;
}
const result = importBundle(this.source, skillsDir, { overwrite: this.overwrite });
if (!result.success && result.imported.length === 0) {
this.context.stderr.write(chalk.red('✗ Failed to import bundle:\n'));
for (const error of result.errors) {
this.context.stderr.write(chalk.red(` - ${error}\n`));
}
return 1;
}
this.context.stdout.write(chalk.green(`✓ Imported ${result.imported.length} skills from bundle!\n`));
for (const name of result.imported) {
this.context.stdout.write(chalk.gray(` + ${name}\n`));
}
if (result.errors.length > 0) {
this.context.stdout.write(chalk.yellow('\nWarnings:\n'));
for (const error of result.errors) {
this.context.stdout.write(chalk.yellow(` - ${error}\n`));
}
}
return 0;
}
}
+288
View File
@@ -0,0 +1,288 @@
import { Command, Option } from 'clipanion';
import { resolve, join } from 'node:path';
import { existsSync, readFileSync, readdirSync } from 'node:fs';
import chalk from 'chalk';
import {
runTestSuite,
createTestSuiteFromFrontmatter,
type SkillTestSuite,
type TestSuiteResult,
} from '@skillkit/core';
import { parse as parseYaml } from 'yaml';
/**
* Test command - run skill tests
*/
export class TestCommand extends Command {
static override paths = [['test']];
static override usage = Command.Usage({
description: 'Run skill tests',
details: `
The test command runs test cases defined in skill frontmatter.
Tests are defined in the skill's YAML frontmatter using the 'tests' key.
Example skill with tests:
\`\`\`yaml
---
name: my-skill
tests:
- name: "Creates config file"
assertions:
- type: file_exists
target: config.json
- name: "Types check"
assertions:
- type: type_check
---
\`\`\`
`,
examples: [
['Run all skill tests', '$0 test'],
['Run tests for a specific skill', '$0 test my-skill'],
['Run with verbose output', '$0 test --verbose'],
['Stop on first failure', '$0 test --bail'],
['Run tests with specific tags', '$0 test --tags unit,integration'],
],
});
skill = Option.String({ required: false });
verbose = Option.Boolean('--verbose,-v', false, {
description: 'Verbose output',
});
bail = Option.Boolean('--bail,-b', false, {
description: 'Stop on first failure',
});
tags = Option.String('--tags,-t', {
description: 'Only run tests with these tags (comma-separated)',
});
skipTags = Option.String('--skip-tags', {
description: 'Skip tests with these tags (comma-separated)',
});
json = Option.Boolean('--json,-j', false, {
description: 'Output results as JSON',
});
projectPath = Option.String('--path,-p', {
description: 'Project path',
});
timeout = Option.String('--timeout', {
description: 'Test timeout in milliseconds',
});
async execute(): Promise<number> {
const targetPath = resolve(this.projectPath || process.cwd());
// Find skills to test
const skillFiles = this.findSkillFiles(targetPath);
if (skillFiles.length === 0) {
if (!this.json) {
console.log(chalk.yellow('No skills found with tests.'));
console.log(chalk.dim('Add tests to your skills using YAML frontmatter.'));
} else {
console.log(JSON.stringify({ results: [], passed: true, total: 0 }));
}
return 0;
}
// Filter by skill name if provided
const filesToTest = this.skill
? skillFiles.filter((f) => f.name.includes(this.skill!))
: skillFiles;
if (filesToTest.length === 0) {
if (!this.json) {
console.log(chalk.yellow(`No skills found matching "${this.skill}"`));
}
return 1;
}
if (!this.json) {
console.log(chalk.bold('Running skill tests...\n'));
}
// Parse tags
const tags = this.tags?.split(',').map((t) => t.trim());
const skipTags = this.skipTags?.split(',').map((t) => t.trim());
const timeout = this.timeout ? parseInt(this.timeout, 10) : undefined;
// Run tests for each skill
const results: TestSuiteResult[] = [];
let allPassed = true;
for (const file of filesToTest) {
const suite = this.parseSkillTests(file.path, file.name);
if (!suite || suite.tests.length === 0) {
continue;
}
if (!this.json) {
console.log(chalk.blue(`Testing: ${suite.skillName}`));
}
const result = await runTestSuite(suite, {
cwd: targetPath,
verbose: this.verbose,
bail: this.bail,
tags,
skipTags,
timeout,
onProgress: (event) => {
if (this.json || !this.verbose) return;
switch (event.type) {
case 'test_start':
console.log(chalk.dim(` Running: ${event.testName}`));
break;
case 'test_end':
if (event.passed) {
console.log(chalk.green(` ✓ ${event.testName}`));
} else {
console.log(chalk.red(` ✗ ${event.testName}`));
if (event.error) {
console.log(chalk.red(` ${event.error}`));
}
}
break;
case 'assertion_end':
if (this.verbose && !event.passed) {
console.log(chalk.red(` - ${event.assertionType}: ${event.error}`));
}
break;
}
},
});
results.push(result);
if (!result.passed) {
allPassed = false;
}
if (!this.json) {
const icon = result.passed ? chalk.green('✓') : chalk.red('✗');
const status = result.passed ? 'PASSED' : 'FAILED';
console.log(
`${icon} ${suite.skillName}: ${result.passedCount}/${result.tests.length} tests ${status} (${result.duration}ms)\n`
);
}
if (this.bail && !result.passed) {
break;
}
}
// Summary
if (this.json) {
console.log(
JSON.stringify({
results: results.map((r) => ({
skill: r.skillName,
passed: r.passed,
tests: r.passedCount,
failed: r.failedCount,
skipped: r.skippedCount,
duration: r.duration,
})),
passed: allPassed,
total: results.length,
})
);
} else {
const totalTests = results.reduce((acc, r) => acc + r.tests.length, 0);
const passedTests = results.reduce((acc, r) => acc + r.passedCount, 0);
const failedTests = results.reduce((acc, r) => acc + r.failedCount, 0);
const skippedTests = results.reduce((acc, r) => acc + r.skippedCount, 0);
console.log(chalk.bold('Summary:'));
console.log(` Skills tested: ${results.length}`);
console.log(` Total tests: ${totalTests}`);
console.log(chalk.green(` Passed: ${passedTests}`));
if (failedTests > 0) {
console.log(chalk.red(` Failed: ${failedTests}`));
}
if (skippedTests > 0) {
console.log(chalk.yellow(` Skipped: ${skippedTests}`));
}
if (allPassed) {
console.log(chalk.green('\n✓ All tests passed!'));
} else {
console.log(chalk.red('\n✗ Some tests failed.'));
}
}
return allPassed ? 0 : 1;
}
/**
* Find skill files with tests
*/
private findSkillFiles(projectPath: string): { name: string; path: string }[] {
const files: { name: string; path: string }[] = [];
// Check common skill directories
const skillDirs = [
'.claude/skills',
'.cursor/skills',
'.skillkit/skills',
'skills',
];
for (const dir of skillDirs) {
const fullDir = join(projectPath, dir);
if (!existsSync(fullDir)) continue;
try {
const entries = readdirSync(fullDir, { withFileTypes: true });
for (const entry of entries) {
if (entry.isFile() && (entry.name.endsWith('.md') || entry.name.endsWith('.mdc'))) {
files.push({
name: entry.name.replace(/\.(md|mdc)$/, ''),
path: join(fullDir, entry.name),
});
}
}
} catch {
// Directory not readable
}
}
return files;
}
/**
* Parse skill file for tests
*/
private parseSkillTests(filePath: string, skillName: string): SkillTestSuite | null {
try {
const content = readFileSync(filePath, 'utf-8');
// Extract frontmatter
const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
if (!frontmatterMatch) {
return null;
}
const frontmatter = parseYaml(frontmatterMatch[1]) as Record<string, unknown>;
if (!frontmatter.tests) {
return null;
}
return createTestSuiteFromFrontmatter(skillName, frontmatter);
} catch {
return null;
}
}
}
@@ -0,0 +1,63 @@
import { Command, Option } from 'clipanion';
import { resolve } from 'node:path';
import chalk from 'chalk';
import { createWorkflowTemplate, saveWorkflow, serializeWorkflow } from '@skillkit/core';
/**
* Workflow Create command - create a new workflow
*/
export class WorkflowCreateCommand extends Command {
static override paths = [['workflow', 'create'], ['wf', 'create'], ['workflow', 'new'], ['wf', 'new']];
static override usage = Command.Usage({
description: 'Create a new workflow',
details: `
The workflow create command creates a new workflow template
that you can customize with your skill composition.
`,
examples: [
['Create a new workflow', '$0 workflow create my-workflow'],
['Create with description', '$0 workflow create setup-project --description "Project setup workflow"'],
['Print to stdout', '$0 workflow create my-workflow --stdout'],
],
});
// Workflow name
workflowName = Option.String({ required: true });
// Description
description = Option.String('--description,-d', {
description: 'Workflow description',
});
// Print to stdout instead of saving
stdout = Option.Boolean('--stdout', false, {
description: 'Print workflow YAML to stdout instead of saving',
});
// Project path
projectPath = Option.String('--path,-p', {
description: 'Project path (default: current directory)',
});
async execute(): Promise<number> {
const targetPath = resolve(this.projectPath || process.cwd());
const workflow = createWorkflowTemplate(this.workflowName, this.description);
if (this.stdout) {
console.log(serializeWorkflow(workflow));
return 0;
}
const filePath = saveWorkflow(targetPath, workflow);
console.log(chalk.green(`✓ Created workflow: ${chalk.bold(this.workflowName)}`));
console.log(chalk.dim(` File: ${filePath}`));
console.log();
console.log(chalk.dim('Edit the workflow file to add skills and configure waves.'));
console.log(chalk.dim('Run with: skillkit workflow run ' + this.workflowName));
return 0;
}
}
@@ -0,0 +1,4 @@
// Workflow command exports
export { WorkflowRunCommand } from './run.js';
export { WorkflowListCommand } from './list.js';
export { WorkflowCreateCommand } from './create.js';
@@ -0,0 +1,94 @@
import { Command, Option } from 'clipanion';
import { resolve } from 'node:path';
import chalk from 'chalk';
import { listWorkflows } from '@skillkit/core';
/**
* Workflow List command - list available workflows
*/
export class WorkflowListCommand extends Command {
static override paths = [['workflow', 'list'], ['wf', 'list'], ['workflow', 'ls'], ['wf', 'ls']];
static override usage = Command.Usage({
description: 'List available workflows',
details: `
The workflow list command shows all available workflows
defined in .skillkit/workflows/
`,
examples: [
['List all workflows', '$0 workflow list'],
['List with details', '$0 workflow list --verbose'],
],
});
// Verbose output
verbose = Option.Boolean('--verbose,-v', false, {
description: 'Show detailed workflow information',
});
// JSON output
json = Option.Boolean('--json,-j', false, {
description: 'Output in JSON format',
});
// Project path
projectPath = Option.String('--path,-p', {
description: 'Project path (default: current directory)',
});
async execute(): Promise<number> {
const targetPath = resolve(this.projectPath || process.cwd());
let workflows: ReturnType<typeof listWorkflows>;
try {
workflows = listWorkflows(targetPath);
} catch (err) {
console.log(chalk.red('Failed to list workflows.'));
console.log(chalk.dim(String(err)));
return 1;
}
if (this.json) {
console.log(JSON.stringify(workflows, null, 2));
return 0;
}
if (workflows.length === 0) {
console.log(chalk.yellow('No workflows found.'));
console.log(chalk.dim('Create a workflow with: skillkit workflow create'));
console.log(chalk.dim('Or add YAML files to .skillkit/workflows/'));
return 0;
}
console.log(chalk.cyan(`Available Workflows (${workflows.length}):\n`));
for (const workflow of workflows) {
console.log(` ${chalk.bold(workflow.name)}`);
if (workflow.description) {
console.log(` ${chalk.dim(workflow.description)}`);
}
if (this.verbose) {
console.log(` Version: ${chalk.dim(workflow.version || 'N/A')}`);
console.log(` Waves: ${chalk.dim(workflow.waves.length.toString())}`);
const totalSkills = workflow.waves.reduce(
(sum, wave) => sum + wave.skills.length,
0
);
console.log(` Total Skills: ${chalk.dim(totalSkills.toString())}`);
if (workflow.tags && workflow.tags.length > 0) {
console.log(` Tags: ${chalk.dim(workflow.tags.join(', '))}`);
}
}
console.log();
}
console.log(chalk.dim('Run a workflow with: skillkit workflow run <name>'));
return 0;
}
}
+248
View File
@@ -0,0 +1,248 @@
import { Command, Option } from 'clipanion';
import { resolve } from 'node:path';
import chalk from 'chalk';
import ora from 'ora';
import {
loadWorkflowByName,
loadWorkflow,
validateWorkflow,
createWorkflowOrchestrator,
createSkillExecutor,
createSimulatedSkillExecutor,
type AgentType,
} from '@skillkit/core';
/**
* Workflow Run command - execute a workflow
*/
export class WorkflowRunCommand extends Command {
static override paths = [['workflow', 'run'], ['wf', 'run']];
static override usage = Command.Usage({
description: 'Execute a skill workflow',
details: `
The workflow run command executes a workflow definition,
running skills in waves with parallel or sequential execution.
Workflows are defined in YAML files in .skillkit/workflows/
`,
examples: [
['Run a workflow by name', '$0 workflow run setup-project'],
['Run a workflow from file', '$0 workflow run --file my-workflow.yaml'],
['Dry run (no execution)', '$0 workflow run setup-project --dry-run'],
],
});
// Workflow name
workflowName = Option.String({ required: false });
// Workflow file path
file = Option.String('--file,-f', {
description: 'Path to workflow YAML file',
});
// Dry run
dryRun = Option.Boolean('--dry-run,-n', false, {
description: 'Show what would be executed without running',
});
// Verbose output
verbose = Option.Boolean('--verbose,-v', false, {
description: 'Show detailed execution progress',
});
// Continue on error
continueOnError = Option.Boolean('--continue-on-error', false, {
description: 'Continue execution even if a skill fails',
});
// JSON output
json = Option.Boolean('--json,-j', false, {
description: 'Output in JSON format',
});
// Project path
projectPath = Option.String('--path,-p', {
description: 'Project path (default: current directory)',
});
// Agent to use for execution
agent = Option.String('--agent,-a', {
description: 'Agent to use for skill execution (e.g., claude-code, codex)',
});
// Simulate execution (for testing)
simulate = Option.Boolean('--simulate', false, {
description: 'Simulate execution without running skills (for testing)',
});
async execute(): Promise<number> {
const targetPath = resolve(this.projectPath || process.cwd());
// Load workflow
let workflow;
try {
if (this.file) {
workflow = loadWorkflow(resolve(this.file));
} else if (this.workflowName) {
workflow = loadWorkflowByName(targetPath, this.workflowName);
if (!workflow) {
console.error(chalk.red(`Workflow "${this.workflowName}" not found`));
console.log(chalk.dim('List available workflows: skillkit workflow list'));
return 1;
}
} else {
console.error(chalk.red('Please specify a workflow name or --file'));
return 1;
}
} catch (error) {
console.error(chalk.red(`Failed to load workflow: ${error}`));
return 1;
}
// Validate workflow
const validation = validateWorkflow(workflow);
if (!validation.valid) {
console.error(chalk.red('Invalid workflow:'));
for (const error of validation.errors) {
console.error(chalk.red(` • ${error}`));
}
return 1;
}
// Dry run mode
if (this.dryRun) {
this.showDryRun(workflow);
return 0;
}
// Execute workflow
console.log(chalk.cyan(`Executing workflow: ${chalk.bold(workflow.name)}`));
if (workflow.description) {
console.log(chalk.dim(workflow.description));
}
console.log();
const spinner = ora();
let currentWave = -1;
// Create the skill executor (real or simulated)
const skillExecutor = this.simulate
? createSimulatedSkillExecutor({
delay: 500,
onExecute: (skillName) => {
if (this.verbose && !this.json) {
console.log(chalk.dim(` [Simulated] ${skillName}`));
}
},
})
: createSkillExecutor({
projectPath: targetPath,
preferredAgent: this.agent as AgentType | undefined,
fallbackToAvailable: true,
onExecutionEvent: (event) => {
if (this.verbose && !this.json) {
switch (event.type) {
case 'skill_found':
console.log(chalk.dim(` Found: ${event.message}`));
break;
case 'skill_not_found':
console.log(chalk.red(` Not found: ${event.skillName}`));
break;
case 'agent_selected':
console.log(chalk.dim(` Agent: ${event.agent}`));
break;
case 'execution_complete':
if (!event.success) {
console.log(chalk.red(` Error: ${event.error}`));
}
break;
}
}
},
});
// Create orchestrator with real skill executor
const orchestrator = createWorkflowOrchestrator(
skillExecutor,
(event) => {
if (this.json) return;
switch (event.type) {
case 'wave_start':
currentWave = event.waveIndex || 0;
spinner.start(`Wave ${currentWave + 1}: ${event.waveName || 'Executing...'}`);
break;
case 'skill_start':
if (this.verbose) {
spinner.text = `Wave ${currentWave + 1}: Running ${event.skillName}...`;
}
break;
case 'skill_complete':
if (this.verbose) {
const icon = event.status === 'completed' ? chalk.green('✓') : chalk.red('✗');
console.log(` ${icon} ${event.skillName}`);
}
break;
case 'wave_complete':
const waveIcon = event.status === 'completed' ? chalk.green('✓') : chalk.red('✗');
spinner.stopAndPersist({
symbol: waveIcon,
text: `Wave ${(event.waveIndex || 0) + 1}: ${event.waveName || 'Complete'}`,
});
break;
case 'workflow_complete':
console.log();
if (event.status === 'completed') {
console.log(chalk.green('✓ Workflow completed successfully'));
} else {
console.log(chalk.red(`✗ Workflow ${event.status}`));
if (event.error) {
console.log(chalk.red(` Error: ${event.error}`));
}
}
break;
}
}
);
const execution = await orchestrator.execute(workflow);
if (this.json) {
console.log(JSON.stringify(execution, null, 2));
}
return execution.status === 'completed' ? 0 : 1;
}
private showDryRun(workflow: { name: string; description?: string; waves: Array<{ name?: string; parallel: boolean; skills: Array<string | { skill: string }> }> }): void {
console.log(chalk.cyan('Dry Run - Workflow Execution Plan'));
console.log();
console.log(`Workflow: ${chalk.bold(workflow.name)}`);
if (workflow.description) {
console.log(`Description: ${chalk.dim(workflow.description)}`);
}
console.log();
for (let i = 0; i < workflow.waves.length; i++) {
const wave = workflow.waves[i];
const modeLabel = wave.parallel ? chalk.blue('[parallel]') : chalk.yellow('[sequential]');
console.log(`${chalk.cyan(`Wave ${i + 1}`)}: ${wave.name || 'Unnamed'} ${modeLabel}`);
for (const skill of wave.skills) {
const skillName = typeof skill === 'string' ? skill : skill.skill;
console.log(` • ${skillName}`);
}
console.log();
}
console.log(chalk.dim('This is a dry run. No skills were executed.'));
console.log(chalk.dim('Remove --dry-run to execute the workflow.'));
}
}
+219
View File
@@ -0,0 +1,219 @@
# @skillkit/core
[![npm version](https://img.shields.io/npm/v/@skillkit/core.svg)](https://www.npmjs.com/package/@skillkit/core)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
**Core engine for SkillKit** - skill discovery, cross-agent translation, recommendations, session memory, testing, and workflow orchestration.
## Installation
```bash
npm install @skillkit/core
```
## Key Features
- **Skill Discovery**: Find and parse SKILL.md files from any source
- **Cross-Agent Translation**: Convert skills between 17 agent formats (Claude Code, Cursor, Windsurf, etc.)
- **Project Context Detection**: Analyze project stack, dependencies, and configurations
- **Smart Recommendations**: AI-powered skill suggestions based on project profile
- **Session Memory**: Capture and persist learnings across AI coding sessions
- **Skill Testing**: Test framework with assertions for skill validation
- **Workflow Orchestration**: Compose skills into multi-step workflows
- **Marketplace Aggregation**: Browse and search curated skill repositories
## Usage
### Skill Discovery
```typescript
import { findAllSkills, discoverSkills, parseSkill } from '@skillkit/core';
// Find all installed skills
const skills = findAllSkills(['.claude/skills', '.cursor/skills']);
// Discover skills from a repository
const repoSkills = await discoverSkills('anthropics/skills');
// Parse a single skill file
const skill = parseSkill('./my-skill/SKILL.md');
```
### Cross-Agent Translation
```typescript
import { translateSkill, translateSkillFile, TranslatorRegistry } from '@skillkit/core';
// Translate skill content to Cursor format
const result = translateSkill(skillContent, 'cursor');
console.log(result.content); // MDC format for Cursor
// Translate a skill file
const translated = await translateSkillFile('./skill.md', 'windsurf');
// Get available translators
const registry = new TranslatorRegistry();
const formats = registry.getSupportedFormats();
```
### Project Context & Recommendations
```typescript
import { ProjectDetector, RecommendationEngine, ContextManager } from '@skillkit/core';
// Detect project context
const detector = new ProjectDetector();
const profile = await detector.analyze('./my-project');
// profile.stack includes: languages, frameworks, libraries, testing tools, etc.
// Get skill recommendations
const engine = new RecommendationEngine();
const recommendations = engine.recommend(profile, availableSkills);
// Returns skills sorted by match score
// Manage project context
const ctx = new ContextManager('./my-project');
await ctx.init();
const context = ctx.getContext();
```
### Session Memory
```typescript
import {
createMemoryCompressor,
createMemoryInjector,
LearningStore,
ObservationStore,
} from '@skillkit/core';
// Compress observations into learnings
const compressor = createMemoryCompressor('./my-project');
const learnings = compressor.compress();
// Inject relevant memories into prompts
const injector = createMemoryInjector('./my-project');
const memories = injector.search('authentication patterns');
// Manage learnings directly
const store = new LearningStore('./my-project');
const learning = store.add({
title: 'React hooks best practices',
content: 'Always cleanup effects...',
tags: ['react', 'hooks'],
});
```
### Skill Testing
```typescript
import { SkillTestRunner, parseTestCases } from '@skillkit/core';
// Run skill tests
const runner = new SkillTestRunner('./my-project');
const results = await runner.runAll();
// Run specific tests
const result = await runner.run('./my-skill', {
tags: ['unit'],
verbose: true,
});
// Parse test cases from skill
const testCases = parseTestCases(skillContent);
```
### Workflow Orchestration
```typescript
import { WorkflowOrchestrator, parseWorkflow, WorkflowStore } from '@skillkit/core';
// Parse and run a workflow
const workflow = parseWorkflow('./workflow.yaml');
const orchestrator = new WorkflowOrchestrator(workflow);
await orchestrator.execute();
// Manage workflows
const store = new WorkflowStore('./my-project');
const workflows = store.list();
```
### Marketplace
```typescript
import { createMarketplaceAggregator, MarketplaceSource } from '@skillkit/core';
// Browse skill marketplace
const marketplace = createMarketplaceAggregator();
const results = await marketplace.search({ query: 'react' });
// Filter by tags
const filtered = await marketplace.search({
query: 'authentication',
tags: ['security', 'auth'],
limit: 10,
});
```
## Supported Agents
The translator supports all 17 SkillKit-compatible agents:
| Agent | Format |
|-------|--------|
| Claude Code | SKILL.md |
| Cursor | MDC (.mdc) |
| Codex | SKILL.md |
| Gemini CLI | SKILL.md |
| Windsurf | Markdown |
| GitHub Copilot | Markdown |
| OpenCode, Antigravity, Amp, Goose, Kilo, Kiro, Roo, Trae | SKILL.md |
| Universal | SKILL.md |
## API Reference
### Skill Types
```typescript
interface CanonicalSkill {
name: string;
description?: string;
version?: string;
author?: string;
tags?: string[];
globs?: string[];
alwaysApply?: boolean;
content: string;
metadata?: Record<string, unknown>;
}
interface TranslationResult {
content: string;
format: string;
warnings?: string[];
}
```
### Context Types
```typescript
interface ProjectProfile {
name: string;
type: 'web-app' | 'api' | 'cli' | 'library' | 'unknown';
stack: {
languages: Detection[];
frameworks: Detection[];
libraries: Detection[];
testing: Detection[];
databases: Detection[];
};
}
```
## Documentation
Full documentation: https://github.com/rohitg00/skillkit
## License
Apache-2.0
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/core",
"version": "1.3.0",
"version": "1.4.0",
"description": "Core functionality for SkillKit - skill discovery, parsing, and translation",
"type": "module",
"main": "./dist/index.js",
+18
View File
@@ -0,0 +1,18 @@
/**
* CI/CD Integration Module
*
* Provides templates and utilities for integrating skill validation
* into CI/CD pipelines.
*/
export * from './templates.js';
export {
GITHUB_ACTION_TEMPLATE,
PRE_COMMIT_HOOK_TEMPLATE,
PRE_COMMIT_CONFIG_TEMPLATE,
GITLAB_CI_TEMPLATE,
CIRCLECI_CONFIG_TEMPLATE,
getCICDTemplate,
listCICDTemplates,
} from './templates.js';
+238
View File
@@ -0,0 +1,238 @@
/**
* CI/CD Templates
*
* Provides templates for GitHub Actions, pre-commit hooks, and other CI/CD integrations.
*/
/**
* GitHub Action workflow for skill validation
*/
export const GITHUB_ACTION_TEMPLATE = `# Skill Validation Workflow
# This workflow validates skills in your repository
name: Validate Skills
on:
push:
paths:
- '.claude/skills/**'
- '.cursor/skills/**'
- 'skills/**'
pull_request:
paths:
- '.claude/skills/**'
- '.cursor/skills/**'
- 'skills/**'
jobs:
validate:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install SkillKit
run: npm install -g skillkit
- name: Validate Skills
run: skillkit validate
- name: Run Skill Tests
run: skillkit test --json > test-results.json
continue-on-error: true
- name: Upload Test Results
uses: actions/upload-artifact@v4
with:
name: skill-test-results
path: test-results.json
retention-days: 30
- name: Check Test Results
run: |
if [ -f test-results.json ]; then
passed=$(cat test-results.json | jq -r '.passed')
if [ "$passed" = "false" ]; then
echo "Some skill tests failed"
exit 1
fi
fi
`;
/**
* Pre-commit hook script for skill validation
*/
export const PRE_COMMIT_HOOK_TEMPLATE = `#!/bin/bash
# SkillKit Pre-commit Hook
# Validates skills before commit
# Colors for output
RED='\\033[0;31m'
GREEN='\\033[0;32m'
YELLOW='\\033[0;33m'
NC='\\033[0m' # No Color
echo -e "\${YELLOW}Running SkillKit validation...\${NC}"
# Check if skillkit is installed
if ! command -v skillkit &> /dev/null; then
echo -e "\${RED}SkillKit not found. Install with: npm install -g skillkit\${NC}"
exit 1
fi
# Get list of staged skill files
SKILL_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\\.(md|mdc)$' | grep -E '(skills|.claude|.cursor)')
if [ -z "$SKILL_FILES" ]; then
echo -e "\${GREEN}No skill files staged, skipping validation.\${NC}"
exit 0
fi
echo "Validating skill files:"
echo "$SKILL_FILES"
# Run validation
if ! skillkit validate; then
echo -e "\${RED}Skill validation failed. Please fix the errors and try again.\${NC}"
exit 1
fi
# Run tests if any
if skillkit test --json 2>/dev/null | jq -e '.passed == false' > /dev/null 2>&1; then
echo -e "\${RED}Skill tests failed. Please fix the failing tests.\${NC}"
exit 1
fi
echo -e "\${GREEN}All skills validated successfully!\${NC}"
exit 0
`;
/**
* Pre-commit config for .pre-commit-config.yaml
*/
export const PRE_COMMIT_CONFIG_TEMPLATE = `# SkillKit Pre-commit Configuration
# Add this to your .pre-commit-config.yaml
repos:
- repo: local
hooks:
- id: skillkit-validate
name: SkillKit Validate
entry: skillkit validate
language: system
files: \\.(md|mdc)$
pass_filenames: false
- id: skillkit-test
name: SkillKit Test
entry: skillkit test
language: system
files: \\.(md|mdc)$
pass_filenames: false
`;
/**
* GitLab CI template
*/
export const GITLAB_CI_TEMPLATE = `# SkillKit GitLab CI Configuration
# Add this to your .gitlab-ci.yml
skill-validation:
image: node:20
stage: test
before_script:
- npm install -g skillkit
script:
- skillkit validate
- skillkit test --json > test-results.json
artifacts:
# Note: test-results.json is JSON format, not JUnit XML
paths:
- test-results.json
expire_in: 30 days
rules:
- changes:
- ".claude/skills/**"
- ".cursor/skills/**"
- "skills/**"
`;
/**
* CircleCI config template
*/
export const CIRCLECI_CONFIG_TEMPLATE = `# SkillKit CircleCI Configuration
# Add this to your .circleci/config.yml
version: 2.1
jobs:
validate-skills:
docker:
- image: cimg/node:20.0
steps:
- checkout
- run:
name: Install SkillKit
command: npm install -g skillkit
- run:
name: Validate Skills
command: skillkit validate
- run:
name: Run Skill Tests
command: skillkit test --json > test-results.json
- store_artifacts:
path: test-results.json
destination: skill-tests
workflows:
skill-validation:
jobs:
- validate-skills:
filters:
branches:
only: /.*/
`;
/**
* Get a CI/CD template by name
*/
export function getCICDTemplate(name: string): string | null {
switch (name.toLowerCase()) {
case 'github':
case 'github-action':
case 'github-actions':
return GITHUB_ACTION_TEMPLATE;
case 'pre-commit':
case 'pre-commit-hook':
return PRE_COMMIT_HOOK_TEMPLATE;
case 'pre-commit-config':
return PRE_COMMIT_CONFIG_TEMPLATE;
case 'gitlab':
case 'gitlab-ci':
return GITLAB_CI_TEMPLATE;
case 'circleci':
case 'circle-ci':
return CIRCLECI_CONFIG_TEMPLATE;
default:
return null;
}
}
/**
* List available CI/CD templates
*/
export function listCICDTemplates(): { name: string; description: string }[] {
return [
{ name: 'github-action', description: 'GitHub Actions workflow for skill validation' },
{ name: 'pre-commit-hook', description: 'Git pre-commit hook script' },
{ name: 'pre-commit-config', description: 'pre-commit framework configuration' },
{ name: 'gitlab-ci', description: 'GitLab CI configuration' },
{ name: 'circleci', description: 'CircleCI configuration' },
];
}
+23 -1
View File
@@ -15,10 +15,32 @@ export function getGlobalConfigPath(): string {
return join(homedir(), '.config', 'skillkit', CONFIG_FILE);
}
export function loadConfig(): SkillkitConfig {
export function loadConfig(global = false): SkillkitConfig {
const projectPath = getProjectConfigPath();
const globalPath = getGlobalConfigPath();
// If global is explicitly requested, only load from global path
if (global) {
if (existsSync(globalPath)) {
try {
const content = readFileSync(globalPath, 'utf-8');
const data = parseYaml(content);
const parsed = SkillkitConfig.safeParse(data);
if (parsed.success) {
return parsed.data;
}
} catch {
// Ignore parse errors
}
}
return {
version: 1,
agent: 'universal',
autoSync: true,
};
}
// Default behavior: project config takes precedence over global
if (existsSync(projectPath)) {
try {
const content = readFileSync(projectPath, 'utf-8');
+11
View File
@@ -40,3 +40,14 @@ export {
type SyncResult,
type SyncReport,
} from './sync.js';
// Loader (Smart Context Loading)
export {
ContextLoader,
createContextLoader,
estimateTokens,
DEFAULT_CONTEXT_CATEGORIES,
type ContextCategory,
type ContextLoadOptions,
type LoadedContext,
} from './loader.js';
+331
View File
@@ -0,0 +1,331 @@
/**
* Context Loader
*
* Smart context loading with token budgets and category-based loading.
*/
import { existsSync, readFileSync, statSync } from 'node:fs';
import { join } from 'node:path';
/**
* Context category with size limits
*/
export interface ContextCategory {
/** Category name */
name: string;
/** Maximum tokens for this category */
maxTokens: number;
/** Whether to always load this category */
alwaysLoad: boolean;
/** File path (relative to project) */
file?: string;
/** Inline content */
content?: string;
}
/**
* Context loading options
*/
export interface ContextLoadOptions {
/** Total token budget */
totalBudget?: number;
/** Categories to load (load all if not specified) */
categories?: string[];
/** Whether to warn when approaching budget limits */
warnOnBudgetLimit?: boolean;
}
/**
* Loaded context result
*/
export interface LoadedContext {
/** All loaded content combined */
content: string;
/** Total tokens used */
totalTokens: number;
/** Budget remaining */
budgetRemaining: number;
/** Categories loaded */
categoriesLoaded: string[];
/** Categories skipped (due to budget or not found) */
categoriesSkipped: string[];
/** Warnings generated */
warnings: string[];
/** Whether budget is near limit (>50% used) */
nearBudgetLimit: boolean;
/** Whether context is degraded (>70% used) */
contextDegraded: boolean;
}
/**
* Default context categories
*/
export const DEFAULT_CONTEXT_CATEGORIES: ContextCategory[] = [
{
name: 'project',
maxTokens: 2000,
alwaysLoad: true,
file: '.skillkit/context.yaml',
},
{
name: 'requirements',
maxTokens: 5000,
alwaysLoad: false,
file: 'REQUIREMENTS.md',
},
{
name: 'decisions',
maxTokens: 1000,
alwaysLoad: false,
file: '.skillkit/decisions.yaml',
},
{
name: 'readme',
maxTokens: 3000,
alwaysLoad: false,
file: 'README.md',
},
];
/**
* Rough estimate of tokens from text
* (approximation: ~4 characters per token for English text)
*/
export function estimateTokens(text: string): number {
return Math.ceil(text.length / 4);
}
/**
* Context Loader class
*/
export class ContextLoader {
private projectPath: string;
private categories: ContextCategory[];
private defaultBudget: number;
constructor(projectPath: string, options?: { categories?: ContextCategory[]; defaultBudget?: number }) {
this.projectPath = projectPath;
this.categories = options?.categories || DEFAULT_CONTEXT_CATEGORIES;
this.defaultBudget = options?.defaultBudget || 32000; // Default ~32k tokens
}
/**
* Load context based on options
*/
load(options: ContextLoadOptions = {}): LoadedContext {
const totalBudget = options.totalBudget || this.defaultBudget;
const requestedCategories = options.categories;
const result: LoadedContext = {
content: '',
totalTokens: 0,
budgetRemaining: totalBudget,
categoriesLoaded: [],
categoriesSkipped: [],
warnings: [],
nearBudgetLimit: false,
contextDegraded: false,
};
const contentParts: string[] = [];
// First pass: load alwaysLoad categories
for (const category of this.categories) {
if (!category.alwaysLoad) continue;
if (requestedCategories && !requestedCategories.includes(category.name)) continue;
this.loadCategory(category, result, contentParts, totalBudget);
}
// Second pass: load requested categories
for (const category of this.categories) {
if (category.alwaysLoad) continue; // Already loaded
if (requestedCategories && !requestedCategories.includes(category.name)) continue;
this.loadCategory(category, result, contentParts, totalBudget);
}
// Combine content
result.content = contentParts.join('\n\n---\n\n');
// Check budget status
const usagePercent = (result.totalTokens / totalBudget) * 100;
result.nearBudgetLimit = usagePercent >= 50;
result.contextDegraded = usagePercent >= 70;
// Add warnings for budget limits
if (result.contextDegraded && options.warnOnBudgetLimit !== false) {
result.warnings.push(
`Context usage at ${Math.round(usagePercent)}% - quality may degrade. Consider spawning a fresh agent.`
);
} else if (result.nearBudgetLimit && options.warnOnBudgetLimit !== false) {
result.warnings.push(`Context usage at ${Math.round(usagePercent)}% - approaching limit.`);
}
return result;
}
/**
* Load a single category
*/
private loadCategory(
category: ContextCategory,
result: LoadedContext,
contentParts: string[],
totalBudget: number
): void {
let content: string | null = null;
// Load from file
if (category.file) {
const filePath = join(this.projectPath, category.file);
if (existsSync(filePath)) {
try {
content = readFileSync(filePath, 'utf-8');
} catch {
result.categoriesSkipped.push(category.name);
return;
}
}
}
// Use inline content if no file
if (!content && category.content) {
content = category.content;
}
if (!content) {
result.categoriesSkipped.push(category.name);
return;
}
// Estimate tokens
const tokens = estimateTokens(content);
// Check category limit
if (tokens > category.maxTokens) {
// Truncate to category limit
const truncateChars = category.maxTokens * 4;
content = content.slice(0, truncateChars) + '\n\n[... content truncated ...]';
result.warnings.push(
`Category "${category.name}" truncated to ${category.maxTokens} tokens`
);
}
// Check total budget
const truncatedTokens = estimateTokens(content);
if (result.totalTokens + truncatedTokens > totalBudget) {
// Skip if would exceed budget
result.categoriesSkipped.push(category.name);
result.warnings.push(
`Category "${category.name}" skipped - would exceed budget`
);
return;
}
// Add to result
contentParts.push(`# ${category.name.toUpperCase()}\n\n${content}`);
result.totalTokens += truncatedTokens;
result.budgetRemaining = totalBudget - result.totalTokens;
result.categoriesLoaded.push(category.name);
}
/**
* Get category by name
*/
getCategory(name: string): ContextCategory | undefined {
return this.categories.find((c) => c.name === name);
}
/**
* Add a custom category
*/
addCategory(category: ContextCategory): void {
const existing = this.categories.findIndex((c) => c.name === category.name);
if (existing >= 0) {
this.categories[existing] = category;
} else {
this.categories.push(category);
}
}
/**
* Remove a category
*/
removeCategory(name: string): void {
this.categories = this.categories.filter((c) => c.name !== name);
}
/**
* Get estimated context size for categories
*/
estimateSize(categoryNames?: string[]): { category: string; tokens: number; available: boolean }[] {
const estimates: { category: string; tokens: number; available: boolean }[] = [];
for (const category of this.categories) {
if (categoryNames && !categoryNames.includes(category.name)) continue;
let tokens = 0;
let available = false;
if (category.file) {
const filePath = join(this.projectPath, category.file);
if (existsSync(filePath)) {
try {
const stat = statSync(filePath);
tokens = Math.ceil(stat.size / 4); // Rough estimate
available = true;
} catch {
// File not accessible
}
}
} else if (category.content) {
tokens = estimateTokens(category.content);
available = true;
}
estimates.push({
category: category.name,
tokens: Math.min(tokens, category.maxTokens),
available,
});
}
return estimates;
}
/**
* Check if context would exceed budget threshold
*/
wouldExceedThreshold(additionalTokens: number, threshold: number = 0.7): boolean {
const currentTokens = this.load().totalTokens;
const newTotal = currentTokens + additionalTokens;
return newTotal / this.defaultBudget > threshold;
}
/**
* Suggest spawning fresh agent if context is degraded
*/
shouldSpawnFreshAgent(): { should: boolean; reason?: string } {
const context = this.load();
if (context.contextDegraded) {
return {
should: true,
reason: `Context at ${Math.round((context.totalTokens / this.defaultBudget) * 100)}% capacity`,
};
}
return { should: false };
}
}
/**
* Create a context loader
*/
export function createContextLoader(
projectPath: string,
options?: { categories?: ContextCategory[]; defaultBudget?: number }
): ContextLoader {
return new ContextLoader(projectPath, options);
}
+348
View File
@@ -0,0 +1,348 @@
/**
* Agent Execution Module
*
* Handles real execution of skills through various AI agent CLIs.
*/
import { spawn, type SpawnOptions } from 'node:child_process';
import type { AgentType } from '../types.js';
/**
* Agent CLI configuration
*/
export interface AgentCLIConfig {
/** Agent type */
type: AgentType;
/** CLI command name */
command: string;
/** Whether the agent supports CLI execution */
supportsCLI: boolean;
/** Arguments to pass the prompt/skill content */
promptArgs?: string[];
/** Arguments for non-interactive mode */
nonInteractiveArgs?: string[];
/** Environment variables needed */
envVars?: Record<string, string>;
/** How to check if agent is installed */
checkCommand?: string;
}
/**
* Execution result from an agent
*/
export interface AgentExecutionResult {
success: boolean;
output: string;
error?: string;
exitCode: number;
duration: number;
}
/**
* Agent CLI configurations
*/
export const AGENT_CLI_CONFIGS: AgentCLIConfig[] = [
{
type: 'claude-code',
command: 'claude',
supportsCLI: true,
promptArgs: ['--print', '-p'],
nonInteractiveArgs: ['--no-input'],
checkCommand: 'claude --version',
},
{
type: 'codex',
command: 'codex',
supportsCLI: true,
promptArgs: ['-p'],
checkCommand: 'codex --version',
},
{
type: 'gemini-cli',
command: 'gemini',
supportsCLI: true,
promptArgs: [],
checkCommand: 'gemini --version',
},
{
type: 'opencode',
command: 'opencode',
supportsCLI: true,
promptArgs: ['--prompt'],
checkCommand: 'opencode --version',
},
{
type: 'goose',
command: 'goose',
supportsCLI: true,
promptArgs: ['run'],
checkCommand: 'goose --version',
},
// IDE-based agents (no CLI execution)
{
type: 'cursor',
command: 'cursor',
supportsCLI: false,
},
{
type: 'windsurf',
command: 'windsurf',
supportsCLI: false,
},
{
type: 'github-copilot',
command: 'gh copilot',
supportsCLI: false,
},
];
/**
* Get CLI config for an agent
*/
export function getAgentCLIConfig(agentType: AgentType): AgentCLIConfig | undefined {
return AGENT_CLI_CONFIGS.find((c) => c.type === agentType);
}
/**
* Check if an agent CLI is available
*/
export async function isAgentCLIAvailable(agentType: AgentType): Promise<boolean> {
const config = getAgentCLIConfig(agentType);
if (!config || !config.supportsCLI) return false;
try {
// Check if command exists
const checkCmd = config.checkCommand || `which ${config.command}`;
const result = await executeCommand(checkCmd.split(' ')[0], checkCmd.split(' ').slice(1), {
timeout: 5000,
});
return result.exitCode === 0;
} catch {
return false;
}
}
/**
* Get all available CLI agents
*/
export async function getAvailableCLIAgents(): Promise<AgentType[]> {
const available: AgentType[] = [];
for (const config of AGENT_CLI_CONFIGS) {
if (config.supportsCLI && (await isAgentCLIAvailable(config.type))) {
available.push(config.type);
}
}
return available;
}
/**
* Execute a skill using an agent CLI
*/
export async function executeWithAgent(
agentType: AgentType,
prompt: string,
options: {
cwd?: string;
timeout?: number;
env?: Record<string, string>;
} = {}
): Promise<AgentExecutionResult> {
const config = getAgentCLIConfig(agentType);
if (!config) {
return {
success: false,
output: '',
error: `Unknown agent type: ${agentType}`,
exitCode: 1,
duration: 0,
};
}
if (!config.supportsCLI) {
return {
success: false,
output: '',
error: `Agent ${agentType} does not support CLI execution. Please use IDE integration.`,
exitCode: 1,
duration: 0,
};
}
const isAvailable = await isAgentCLIAvailable(agentType);
if (!isAvailable) {
return {
success: false,
output: '',
error: `Agent CLI '${config.command}' is not installed or not in PATH`,
exitCode: 1,
duration: 0,
};
}
// Build command arguments
const args: string[] = [...(config.promptArgs || [])];
// For Claude Code, use --print mode with the prompt
if (agentType === 'claude-code') {
args.push(prompt);
} else {
// For other agents, pass prompt as argument
args.push(prompt);
}
// Add non-interactive flags if available
if (config.nonInteractiveArgs) {
args.push(...config.nonInteractiveArgs);
}
return executeCommand(config.command, args, {
cwd: options.cwd || process.cwd(),
timeout: options.timeout || 300000, // 5 minutes default
env: {
...process.env,
...config.envVars,
...options.env,
},
});
}
/**
* Execute a command and capture output
*/
async function executeCommand(
command: string,
args: string[],
options: {
cwd?: string;
timeout?: number;
env?: NodeJS.ProcessEnv;
} = {}
): Promise<AgentExecutionResult> {
return new Promise((resolve) => {
const startTime = Date.now();
let stdout = '';
let stderr = '';
let timedOut = false;
const spawnOptions: SpawnOptions = {
cwd: options.cwd,
env: options.env as NodeJS.ProcessEnv,
// shell: false (default) - prevents shell injection when passing untrusted input
};
const child = spawn(command, args, spawnOptions);
// Set up timeout
const timeoutId = options.timeout
? setTimeout(() => {
timedOut = true;
child.kill('SIGTERM');
}, options.timeout)
: null;
child.stdout?.on('data', (data) => {
stdout += data.toString();
});
child.stderr?.on('data', (data) => {
stderr += data.toString();
});
child.on('error', (error) => {
if (timeoutId) clearTimeout(timeoutId);
resolve({
success: false,
output: stdout,
error: error.message,
exitCode: 1,
duration: Date.now() - startTime,
});
});
child.on('close', (code) => {
if (timeoutId) clearTimeout(timeoutId);
resolve({
success: code === 0 && !timedOut,
output: stdout,
error: timedOut ? 'Execution timed out' : stderr || undefined,
exitCode: code ?? 1,
duration: Date.now() - startTime,
});
});
});
}
/**
* Format skill content as a prompt for an agent
*/
export function formatSkillAsPrompt(
skillName: string,
skillContent: string,
taskDescription?: string
): string {
let prompt = `Execute the following skill: ${skillName}\n\n`;
if (taskDescription) {
prompt += `Task: ${taskDescription}\n\n`;
}
prompt += `Skill Content:\n${skillContent}`;
return prompt;
}
/**
* Agent execution strategy
*/
export type ExecutionStrategy = 'cli' | 'ide' | 'api' | 'manual';
/**
* Get recommended execution strategy for an agent
*/
export function getExecutionStrategy(agentType: AgentType): ExecutionStrategy {
const config = getAgentCLIConfig(agentType);
if (config?.supportsCLI) {
return 'cli';
}
// IDE-based agents
if (['cursor', 'windsurf', 'github-copilot', 'kilo'].includes(agentType)) {
return 'ide';
}
return 'manual';
}
/**
* Get instructions for manual/IDE execution
*/
export function getManualExecutionInstructions(
agentType: AgentType,
skillPath: string
): string {
const strategy = getExecutionStrategy(agentType);
if (strategy === 'ide') {
return `
To execute this skill with ${agentType}:
1. Open your project in ${agentType}
2. The skill has been synced to the agent's skills directory
3. Open the AI assistant/chat
4. Reference the skill or ask the assistant to follow the instructions
Skill location: ${skillPath}
`;
}
return `
To execute this skill manually:
1. Open the skill file: ${skillPath}
2. Copy the skill content
3. Paste it into your AI coding assistant
4. Follow the instructions in the skill
`;
}
+611
View File
@@ -0,0 +1,611 @@
/**
* Skill Execution Engine
*
* Executes skills with task-based orchestration, verification, and state management.
*/
import { execSync } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import type {
ExecutableSkill,
ExecutableTask,
ExecutionOptions,
TaskExecutionResult,
SkillExecutionResult,
CheckpointHandler,
CheckpointResponse,
ExecutionTaskStatus,
} from './types.js';
import { SessionManager } from '../session/manager.js';
import type { SessionTask } from '../session/types.js';
/**
* Progress event for execution
*/
export interface ExecutionProgressEvent {
type: 'task_start' | 'task_complete' | 'checkpoint' | 'verification' | 'complete';
taskId?: string;
taskName?: string;
taskIndex?: number;
totalTasks?: number;
status?: ExecutionTaskStatus | 'paused' | 'cancelled';
message?: string;
error?: string;
}
/**
* Progress callback type
*/
export type ExecutionProgressCallback = (event: ExecutionProgressEvent) => void;
/**
* Skill Execution Engine
*/
export class SkillExecutionEngine {
private projectPath: string;
private sessionManager: SessionManager;
private checkpointHandler?: CheckpointHandler;
private onProgress?: ExecutionProgressCallback;
constructor(
projectPath: string,
options?: {
checkpointHandler?: CheckpointHandler;
onProgress?: ExecutionProgressCallback;
}
) {
this.projectPath = projectPath;
this.sessionManager = new SessionManager(projectPath);
this.checkpointHandler = options?.checkpointHandler;
this.onProgress = options?.onProgress;
}
/**
* Execute a skill
*/
async execute(
skill: ExecutableSkill,
options: ExecutionOptions = {}
): Promise<SkillExecutionResult> {
const startTime = new Date();
const tasks = skill.tasks || [];
// Handle dry run
if (options.dryRun) {
return this.createDryRunResult(skill);
}
// Check if there's an existing paused execution for this skill
const existingState = this.sessionManager.get();
if (existingState?.currentExecution?.skillName === skill.name) {
if (existingState.currentExecution.status === 'paused') {
// Resume from paused state
return this.resumeExecution(skill, options);
}
}
// Start new execution
const sessionTasks: Omit<SessionTask, 'status'>[] = tasks.map((task, index) => ({
id: task.id || `task-${index}`,
name: task.name,
type: task.type === 'auto' ? 'auto' : task.type,
}));
this.sessionManager.startExecution(skill.name, skill.source, sessionTasks);
const taskResults: TaskExecutionResult[] = [];
let overallStatus: 'completed' | 'failed' | 'cancelled' | 'paused' = 'completed';
let overallError: string | undefined;
// Execute tasks
for (let i = 0; i < tasks.length; i++) {
const task = tasks[i];
this.onProgress?.({
type: 'task_start',
taskId: task.id,
taskName: task.name,
taskIndex: i,
totalTasks: tasks.length,
});
// Handle checkpoints
if (task.type !== 'auto') {
const checkpointResult = await this.handleCheckpoint(task, {
skillName: skill.name,
taskIndex: i,
totalTasks: tasks.length,
});
if (!checkpointResult.continue) {
overallStatus = 'paused';
this.sessionManager.pause();
break;
}
// For decision checkpoints, record the decision
if (task.type === 'checkpoint:decision' && checkpointResult.selectedOption) {
this.sessionManager.recordDecision(
`${skill.name}:${task.id}`,
checkpointResult.selectedOption,
skill.name
);
}
}
// Execute the task
const taskResult = await this.executeTask(task, skill, options);
taskResults.push(taskResult);
this.sessionManager.updateTask(task.id || `task-${i}`, {
status: taskResult.status === 'completed' ? 'completed' : 'failed',
output: taskResult.output,
error: taskResult.error,
filesModified: taskResult.filesModified,
commitSha: taskResult.commitSha,
});
this.onProgress?.({
type: 'task_complete',
taskId: task.id,
taskName: task.name,
taskIndex: i,
totalTasks: tasks.length,
status: taskResult.status,
error: taskResult.error,
});
// Handle task failure
if (taskResult.status === 'failed') {
if (!options.continueOnError) {
overallStatus = 'failed';
overallError = taskResult.error;
break;
}
}
// Run verification if enabled
if (options.verify && task.verify) {
const verificationPassed = await this.runVerification(task, taskResult);
if (!verificationPassed && !options.continueOnError) {
overallStatus = 'failed';
overallError = 'Verification failed';
break;
}
}
}
const endTime = new Date();
// Complete the execution
if (overallStatus !== 'paused') {
this.sessionManager.completeExecution(overallStatus, overallError);
}
const result: SkillExecutionResult = {
skillName: skill.name,
skillSource: skill.source,
status: overallStatus,
startedAt: startTime.toISOString(),
completedAt: endTime.toISOString(),
durationMs: endTime.getTime() - startTime.getTime(),
tasks: taskResults,
filesModified: Array.from(new Set(taskResults.flatMap((t) => t.filesModified || []))),
commits: taskResults.map((t) => t.commitSha).filter((sha): sha is string => !!sha),
error: overallError,
};
const statusMessages: Record<'completed' | 'failed' | 'cancelled' | 'paused', string> = {
completed: 'Skill execution completed',
paused: 'Skill execution paused',
failed: overallError || 'Skill execution failed',
cancelled: 'Skill execution cancelled',
};
this.onProgress?.({
type: 'complete',
status: overallStatus,
message: statusMessages[overallStatus],
});
return result;
}
/**
* Resume a paused execution
*/
private async resumeExecution(
skill: ExecutableSkill,
options: ExecutionOptions
): Promise<SkillExecutionResult> {
const state = this.sessionManager.get();
if (!state?.currentExecution) {
throw new Error('No execution to resume');
}
this.sessionManager.resume();
const execution = state.currentExecution;
const tasks = skill.tasks || [];
const taskResults: TaskExecutionResult[] = [];
let overallStatus: 'completed' | 'failed' | 'cancelled' | 'paused' = 'completed';
let overallError: string | undefined;
// Find where to resume from
const startIndex = execution.currentStep;
for (let i = startIndex; i < tasks.length; i++) {
const task = tasks[i];
this.onProgress?.({
type: 'task_start',
taskId: task.id,
taskName: task.name,
taskIndex: i,
totalTasks: tasks.length,
});
// Handle checkpoints (same as in execute)
if (task.type !== 'auto') {
const checkpointResult = await this.handleCheckpoint(task, {
skillName: skill.name,
taskIndex: i,
totalTasks: tasks.length,
});
if (!checkpointResult.continue) {
overallStatus = 'paused';
this.sessionManager.pause();
break;
}
// For decision checkpoints, record the decision
if (task.type === 'checkpoint:decision' && checkpointResult.selectedOption) {
this.sessionManager.recordDecision(
`${skill.name}:${task.id}`,
checkpointResult.selectedOption,
skill.name
);
}
}
const taskResult = await this.executeTask(task, skill, options);
taskResults.push(taskResult);
this.sessionManager.updateTask(task.id || `task-${i}`, {
status: taskResult.status === 'completed' ? 'completed' : 'failed',
output: taskResult.output,
error: taskResult.error,
filesModified: taskResult.filesModified,
commitSha: taskResult.commitSha,
});
// Emit task_complete progress event (matching execute behavior)
this.onProgress?.({
type: 'task_complete',
taskId: task.id,
taskName: task.name,
taskIndex: i,
totalTasks: tasks.length,
status: taskResult.status,
error: taskResult.error,
});
// Handle task failure
if (taskResult.status === 'failed') {
if (!options.continueOnError) {
overallStatus = 'failed';
overallError = taskResult.error;
break;
}
}
// Run verification if enabled (matching execute behavior)
if (options.verify && task.verify) {
const verificationPassed = await this.runVerification(task, taskResult);
if (!verificationPassed && !options.continueOnError) {
overallStatus = 'failed';
overallError = 'Verification failed';
break;
}
}
}
// Only complete execution if not paused
if (overallStatus !== 'paused') {
this.sessionManager.completeExecution(overallStatus, overallError);
}
return {
skillName: skill.name,
skillSource: skill.source,
status: overallStatus,
startedAt: execution.startedAt,
completedAt: new Date().toISOString(),
durationMs: Date.now() - new Date(execution.startedAt).getTime(),
tasks: taskResults,
filesModified: Array.from(new Set(taskResults.flatMap((t) => t.filesModified || []))),
commits: taskResults.map((t) => t.commitSha).filter((sha): sha is string => !!sha),
error: overallError,
};
}
/**
* Execute a single task
*/
private async executeTask(
task: ExecutableTask,
_skill: ExecutableSkill,
_options: ExecutionOptions
): Promise<TaskExecutionResult> {
const startTime = new Date();
const taskId = task.id || randomUUID();
try {
// For now, we simulate task execution
// In a real implementation, this would integrate with the AI agent
// to execute the task action based on the skill content
// Simulate some work
await new Promise((resolve) => setTimeout(resolve, 100));
const endTime = new Date();
return {
taskId,
taskName: task.name,
status: 'completed',
startedAt: startTime.toISOString(),
completedAt: endTime.toISOString(),
durationMs: endTime.getTime() - startTime.getTime(),
output: `Task "${task.name}" completed successfully`,
filesModified: task.files,
};
} catch (error) {
const endTime = new Date();
return {
taskId,
taskName: task.name,
status: 'failed',
startedAt: startTime.toISOString(),
completedAt: endTime.toISOString(),
durationMs: endTime.getTime() - startTime.getTime(),
error: error instanceof Error ? error.message : String(error),
};
}
}
/**
* Handle a checkpoint
*/
private async handleCheckpoint(
task: ExecutableTask,
context: { skillName: string; taskIndex: number; totalTasks: number }
): Promise<CheckpointResponse> {
this.onProgress?.({
type: 'checkpoint',
taskId: task.id,
taskName: task.name,
taskIndex: context.taskIndex,
totalTasks: context.totalTasks,
message: `Checkpoint: ${task.type}`,
});
if (this.checkpointHandler) {
return this.checkpointHandler(task, context);
}
// Default: auto-continue for non-decision checkpoints
if (task.type === 'checkpoint:decision') {
// Use first option if no handler
return {
continue: true,
selectedOption: task.options?.[0],
};
}
return { continue: true };
}
/**
* Check if a regex pattern is potentially dangerous (ReDoS-vulnerable)
* Rejects patterns with nested quantifiers and other known problematic constructs
*/
private isUnsafeRegexPattern(pattern: string): boolean {
// Detect nested quantifiers like (a+)+, (a*)+, (a+)*, (a*)*
// These are the primary cause of catastrophic backtracking
const nestedQuantifierPattern = /\([^)]*[+*][^)]*\)[+*?]/;
if (nestedQuantifierPattern.test(pattern)) {
return true;
}
// Detect overlapping alternations with quantifiers like (a|a)+
const overlappingAlternation = /\([^|)]*\|[^|)]*\)[+*]/;
if (overlappingAlternation.test(pattern)) {
return true;
}
// Detect excessive quantifiers (more than 3 quantifiers in a row-ish)
const quantifierCount = (pattern.match(/[+*?]|\{\d+/g) || []).length;
if (quantifierCount > 10) {
return true;
}
// Detect very long character classes which can be slow
const longCharClass = /\[[^\]]{50,}\]/;
if (longCharClass.test(pattern)) {
return true;
}
return false;
}
/**
* Safely test a regex pattern with ReDoS prevention
*
* This method validates patterns before execution to prevent catastrophic backtracking.
* Note: This cannot guarantee protection against all ReDoS patterns, but catches common ones.
*/
private safeRegexTest(pattern: string, input: string, _timeoutMs = 1000): boolean {
// Strict length limits to prevent excessive processing
if (pattern.length > 200 || input.length > 50000) {
console.warn(`Regex test skipped: pattern or input too long`);
return false;
}
// Reject patterns known to cause ReDoS
if (this.isUnsafeRegexPattern(pattern)) {
console.warn(`Regex pattern rejected as potentially unsafe: ${pattern.slice(0, 50)}...`);
return false;
}
try {
const regex = new RegExp(pattern);
return regex.test(input);
} catch {
// Invalid regex pattern
return false;
}
}
/**
* Run verification for a task
*
* SECURITY NOTE: Verification commands are executed from skill configuration.
* Only run skills from trusted sources. Commands run with the same privileges
* as the skillkit process.
*/
private async runVerification(
task: ExecutableTask,
result: TaskExecutionResult
): Promise<boolean> {
if (!task.verify) {
return true;
}
const verificationResults = {
automated: [] as { rule: string; passed: boolean; output?: string }[],
human: [] as { description: string; passed: boolean }[],
};
// Run automated verification
if (task.verify.automated) {
for (const rule of task.verify.automated) {
if (rule.command) {
try {
// SECURITY: Commands are from skill config - only run trusted skills
const output = execSync(rule.command, {
cwd: this.projectPath,
encoding: 'utf-8',
timeout: 30000,
});
let passed = true;
if (rule.expect) {
if (rule.expect === 'success') {
passed = true;
} else if (rule.expect.startsWith('contains:')) {
const expected = rule.expect.slice(9);
passed = output.includes(expected);
} else if (rule.expect.startsWith('matches:')) {
const pattern = rule.expect.slice(8);
// Use safe regex test to prevent ReDoS
passed = this.safeRegexTest(pattern, output);
}
}
verificationResults.automated.push({
rule: rule.command,
passed,
output,
});
this.onProgress?.({
type: 'verification',
taskId: task.id,
taskName: task.name,
message: `Verification ${passed ? 'passed' : 'failed'}: ${rule.command}`,
});
if (!passed) {
return false;
}
} catch (error) {
verificationResults.automated.push({
rule: rule.command,
passed: false,
output: error instanceof Error ? error.message : String(error),
});
return false;
}
}
}
}
// Human verification would be handled by checkpoint handler
result.verificationResults = verificationResults;
return true;
}
/**
* Create a dry run result
*/
private createDryRunResult(skill: ExecutableSkill): SkillExecutionResult {
const tasks = skill.tasks || [];
return {
skillName: skill.name,
skillSource: skill.source,
status: 'completed',
startedAt: new Date().toISOString(),
completedAt: new Date().toISOString(),
durationMs: 0,
tasks: tasks.map((task) => ({
taskId: task.id || randomUUID(),
taskName: task.name,
status: 'skipped' as ExecutionTaskStatus,
startedAt: new Date().toISOString(),
completedAt: new Date().toISOString(),
durationMs: 0,
output: '[Dry run - not executed]',
})),
filesModified: [],
commits: [],
};
}
/**
* Pause current execution
*/
pause(): boolean {
return this.sessionManager.pause();
}
/**
* Check if execution is paused
*/
isPaused(): boolean {
return this.sessionManager.isPaused();
}
/**
* Get session manager
*/
getSessionManager(): SessionManager {
return this.sessionManager;
}
}
/**
* Create a new skill execution engine
*/
export function createExecutionEngine(
projectPath: string,
options?: {
checkpointHandler?: CheckpointHandler;
onProgress?: ExecutionProgressCallback;
}
): SkillExecutionEngine {
return new SkillExecutionEngine(projectPath, options);
}
+34
View File
@@ -0,0 +1,34 @@
/**
* Skill Execution Engine Module
*
* Provides skill execution with task-based orchestration,
* verification, and session state management.
*/
export * from './types.js';
export * from './engine.js';
export { SkillExecutionEngine, createExecutionEngine } from './engine.js';
// Agent Execution (Real CLI integration)
export * from './agents.js';
export {
executeWithAgent,
isAgentCLIAvailable,
getAvailableCLIAgents,
getAgentCLIConfig,
formatSkillAsPrompt,
getExecutionStrategy,
getManualExecutionInstructions,
AGENT_CLI_CONFIGS,
type AgentCLIConfig,
type AgentExecutionResult,
type ExecutionStrategy,
} from './agents.js';
// Skill Executor for Workflows
export {
createSkillExecutor,
createSimulatedSkillExecutor,
type SkillExecutorOptions,
type SkillExecutionEvent,
} from './skill-executor.js';
@@ -0,0 +1,251 @@
/**
* Skill Executor for Workflows
*
* Provides a real skill executor that finds skills by name
* and executes them using available agent CLIs.
*/
import { existsSync } from 'node:fs';
import { join } from 'node:path';
import { homedir } from 'node:os';
import { findSkill, readSkillContent, SKILL_DISCOVERY_PATHS } from '../skills.js';
import type { AgentType } from '../types.js';
import {
executeWithAgent,
getAvailableCLIAgents,
formatSkillAsPrompt,
getExecutionStrategy,
getManualExecutionInstructions,
} from './agents.js';
import type { SkillExecutor } from '../workflow/orchestrator.js';
/**
* Options for creating a skill executor
*/
export interface SkillExecutorOptions {
/** Project path to search for skills */
projectPath?: string;
/** Preferred agent to use for execution */
preferredAgent?: AgentType;
/** Timeout for skill execution (ms) */
timeout?: number;
/** Whether to fall back to other agents if preferred is unavailable */
fallbackToAvailable?: boolean;
/** Callback for execution events */
onExecutionEvent?: (event: SkillExecutionEvent) => void;
}
/**
* Skill execution event
*/
export interface SkillExecutionEvent {
type: 'skill_found' | 'skill_not_found' | 'agent_selected' | 'execution_start' | 'execution_complete';
skillName: string;
agent?: AgentType;
message?: string;
success?: boolean;
error?: string;
}
/**
* Get search directories for skills
*/
function getSearchDirs(projectPath: string): string[] {
const dirs: string[] = [];
// Project-local paths
for (const searchPath of SKILL_DISCOVERY_PATHS) {
const fullPath = join(projectPath, searchPath);
if (existsSync(fullPath)) {
dirs.push(fullPath);
}
}
// Global paths
const home = homedir();
const globalPaths = [
join(home, '.claude', 'skills'),
join(home, '.cursor', 'skills'),
join(home, '.codex', 'skills'),
join(home, '.skillkit', 'skills'),
];
for (const globalPath of globalPaths) {
if (existsSync(globalPath)) {
dirs.push(globalPath);
}
}
return dirs;
}
/**
* Create a skill executor for workflow orchestration
*
* This returns a function compatible with the WorkflowOrchestrator's SkillExecutor type.
*/
export function createSkillExecutor(options: SkillExecutorOptions = {}): SkillExecutor {
const {
projectPath = process.cwd(),
preferredAgent,
timeout = 300000, // 5 minutes
fallbackToAvailable = true,
onExecutionEvent,
} = options;
return async (skillName: string, config?: Record<string, unknown>): Promise<{ success: boolean; error?: string }> => {
// Find the skill
const searchDirs = getSearchDirs(projectPath);
const skill = findSkill(skillName, searchDirs);
if (!skill) {
onExecutionEvent?.({
type: 'skill_not_found',
skillName,
message: `Skill "${skillName}" not found in any search directory`,
});
return {
success: false,
error: `Skill "${skillName}" not found. Search paths: ${searchDirs.join(', ')}`,
};
}
onExecutionEvent?.({
type: 'skill_found',
skillName,
message: `Found skill at: ${skill.path}`,
});
// Read skill content
const content = readSkillContent(skill.path);
if (!content) {
return {
success: false,
error: `Could not read skill content from: ${skill.path}`,
};
}
// Determine which agent to use
let agentToUse: AgentType | undefined = preferredAgent;
if (!agentToUse || fallbackToAvailable) {
const availableAgents = await getAvailableCLIAgents();
if (preferredAgent && availableAgents.includes(preferredAgent)) {
agentToUse = preferredAgent;
} else if (availableAgents.length > 0) {
// Prefer claude-code if available, otherwise use first available
agentToUse = availableAgents.includes('claude-code') ? 'claude-code' : availableAgents[0];
}
}
// If no CLI agent available, provide manual instructions or error
if (!agentToUse) {
const strategy = getExecutionStrategy(preferredAgent || 'universal');
const instructions = getManualExecutionInstructions(preferredAgent || 'universal', skill.path);
if (strategy === 'ide' || strategy === 'manual') {
onExecutionEvent?.({
type: 'execution_complete',
skillName,
success: false,
message: 'No CLI agent available',
error: `No CLI agent available for execution.\n${instructions}`,
});
return {
success: false,
error: `No CLI agent available for automated execution. ${instructions}`,
};
}
// strategy is 'cli' but the preferred agent's CLI is not installed
const errorMsg = preferredAgent
? `The preferred agent "${preferredAgent}" supports CLI execution but its CLI is not installed.`
: 'No CLI agent is available for execution.';
onExecutionEvent?.({
type: 'execution_complete',
skillName,
success: false,
message: 'CLI not installed',
error: `${errorMsg}\n${instructions}`,
});
return {
success: false,
error: `${errorMsg} ${instructions}`,
};
}
onExecutionEvent?.({
type: 'agent_selected',
skillName,
agent: agentToUse,
message: `Using agent: ${agentToUse}`,
});
// Format the prompt with skill content and any config
let taskDescription: string | undefined;
if (config?.task) {
taskDescription = String(config.task);
}
const prompt = formatSkillAsPrompt(skillName, content, taskDescription);
onExecutionEvent?.({
type: 'execution_start',
skillName,
agent: agentToUse,
message: `Starting execution with ${agentToUse}`,
});
// Execute with the agent
const result = await executeWithAgent(agentToUse!, prompt, {
cwd: projectPath,
timeout,
});
onExecutionEvent?.({
type: 'execution_complete',
skillName,
agent: agentToUse,
success: result.success,
error: result.error,
message: result.success ? 'Execution completed successfully' : `Execution failed: ${result.error}`,
});
return {
success: result.success,
error: result.error,
};
};
}
/**
* Create a simulated skill executor for testing/dry-run
*
* This executor doesn't actually run skills but simulates execution.
*/
export function createSimulatedSkillExecutor(options: {
delay?: number;
shouldFail?: (skillName: string) => boolean;
onExecute?: (skillName: string) => void;
} = {}): SkillExecutor {
const { delay = 100, shouldFail, onExecute } = options;
return async (skillName: string, _config?: Record<string, unknown>): Promise<{ success: boolean; error?: string }> => {
onExecute?.(skillName);
// Simulate execution time
await new Promise((resolve) => setTimeout(resolve, delay));
const failed = shouldFail?.(skillName) ?? false;
return {
success: !failed,
error: failed ? `Simulated failure for skill: ${skillName}` : undefined,
};
};
}
+179
View File
@@ -0,0 +1,179 @@
/**
* Executor Types
*
* Types for skill execution engine.
*/
import type { AgentType } from '../types.js';
/**
* Task type within a skill
*/
export type ExecutableTaskType =
| 'auto'
| 'checkpoint:human-verify'
| 'checkpoint:decision'
| 'checkpoint:human-action';
/**
* Task status
*/
export type ExecutionTaskStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
/**
* Verification rule for a task
*/
export interface VerificationRule {
/** Command to run for verification */
command?: string;
/** Expected result (success, contains:<text>, matches:<regex>) */
expect?: string;
/** Human verification prompt */
description?: string;
/** URL to show for verification */
url?: string;
}
/**
* An executable task within a skill
*/
export interface ExecutableTask {
/** Task identifier */
id: string;
/** Task name/description */
name: string;
/** Task type */
type: ExecutableTaskType;
/** Action description for AI agent */
action: string;
/** Files expected to be modified */
files?: string[];
/** Verification rules */
verify?: {
automated?: VerificationRule[];
human?: VerificationRule[];
};
/** Options for checkpoint:decision type */
options?: string[];
/** Dependencies (task IDs that must complete first) */
dependsOn?: string[];
}
/**
* Extended skill with execution metadata
*/
export interface ExecutableSkill {
/** Skill name */
name: string;
/** Skill description */
description?: string;
/** Skill version */
version?: string;
/** Skill source (repo or path) */
source: string;
/** Skill content (instructions) */
content: string;
/** Executable tasks */
tasks?: ExecutableTask[];
/** Environment requirements */
requirements?: {
frameworks?: string[];
languages?: string[];
libraries?: string[];
};
}
/**
* Task execution result
*/
export interface TaskExecutionResult {
/** Task ID */
taskId: string;
/** Task name */
taskName: string;
/** Final status */
status: ExecutionTaskStatus;
/** Start time */
startedAt: string;
/** End time (only present for completed/failed/skipped tasks) */
completedAt?: string;
/** Duration in milliseconds (only present for completed/failed/skipped tasks) */
durationMs?: number;
/** Output/result */
output?: string;
/** Error message if failed */
error?: string;
/** Files modified */
filesModified?: string[];
/** Git commit SHA if committed */
commitSha?: string;
/** Verification results */
verificationResults?: {
automated: { rule: string; passed: boolean; output?: string }[];
human: { description: string; passed: boolean }[];
};
}
/**
* Skill execution result
*/
export interface SkillExecutionResult {
/** Skill name */
skillName: string;
/** Skill source */
skillSource: string;
/** Overall status */
status: 'completed' | 'failed' | 'cancelled' | 'paused';
/** Start time */
startedAt: string;
/** End time */
completedAt?: string;
/** Total duration in milliseconds */
durationMs?: number;
/** Task results */
tasks: TaskExecutionResult[];
/** All files modified */
filesModified: string[];
/** All commits created */
commits: string[];
/** Error if failed */
error?: string;
}
/**
* Execution options
*/
export interface ExecutionOptions {
/** Target agent to use */
agent?: AgentType;
/** Whether to create commits per task */
autoCommit?: boolean;
/** Whether to run verification checks */
verify?: boolean;
/** Dry run (show what would be done) */
dryRun?: boolean;
/** Continue on task failure */
continueOnError?: boolean;
/** Environment variables to set */
env?: Record<string, string>;
}
/**
* Checkpoint response from user
*/
export interface CheckpointResponse {
/** Whether to continue */
continue: boolean;
/** Selected option (for decision checkpoints) */
selectedOption?: string;
/** User notes */
notes?: string;
}
/**
* Checkpoint handler function type
*/
export type CheckpointHandler = (
task: ExecutableTask,
context: { skillName: string; taskIndex: number; totalTasks: number }
) => Promise<CheckpointResponse>;
+27
View File
@@ -18,3 +18,30 @@ export * from './context/index.js';
// Recommendation Engine (Smart Recommendations)
export * from './recommend/index.js';
// Session Management (Pause/Resume Support)
export * from './session/index.js';
// Workflow Orchestration (Skill Composition)
export * from './workflow/index.js';
// Skill Execution Engine
export * from './executor/index.js';
// Skill Testing Framework
export * from './testing/index.js';
// Skill Marketplace (Aggregated Index)
export * from './marketplace/index.js';
// CI/CD Integration (Templates & Utilities)
export * from './cicd/index.js';
// Memory System (Cross-Agent Session Memory)
export * from './memory/index.js';
// Team Collaboration (Skill Sharing)
export * from './team/index.js';
// Plugin System (Extensibility)
export * from './plugins/index.js';
+526
View File
@@ -0,0 +1,526 @@
/**
* Marketplace Aggregator
*
* Fetches and indexes skills from multiple GitHub repositories.
*/
import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'node:fs';
import { join } from 'node:path';
import { homedir } from 'node:os';
import type {
SkillSource,
MarketplaceSkill,
MarketplaceIndex,
MarketplaceSearchOptions,
MarketplaceSearchResult,
MarketplaceConfig,
} from './types.js';
import {
DEFAULT_SKILL_SOURCES,
MARKETPLACE_CACHE_FILE,
DEFAULT_CACHE_TTL,
} from './types.js';
/**
* Marketplace Aggregator
*/
export class MarketplaceAggregator {
private config: MarketplaceConfig;
private cacheDir: string;
private cachePath: string;
private index: MarketplaceIndex | null = null;
constructor(config: MarketplaceConfig = {}) {
this.config = config;
this.cacheDir = config.cacheDir || join(homedir(), '.skillkit', 'marketplace');
this.cachePath = join(this.cacheDir, MARKETPLACE_CACHE_FILE);
// Ensure cache directory exists
if (!existsSync(this.cacheDir)) {
mkdirSync(this.cacheDir, { recursive: true });
}
}
/**
* Get all sources (default + custom)
*/
getSources(): SkillSource[] {
return [...DEFAULT_SKILL_SOURCES, ...(this.config.sources || [])];
}
/**
* Load cached index
*/
loadCache(): MarketplaceIndex | null {
if (!existsSync(this.cachePath)) {
return null;
}
try {
const content = readFileSync(this.cachePath, 'utf-8');
const index = JSON.parse(content) as MarketplaceIndex;
// Check if cache is expired
const cacheAge = Date.now() - new Date(index.updatedAt).getTime();
const ttl = this.config.cacheTTL || DEFAULT_CACHE_TTL;
if (cacheAge > ttl) {
return null; // Cache expired
}
this.index = index;
return index;
} catch {
return null;
}
}
/**
* Save index to cache
*/
saveCache(index: MarketplaceIndex): void {
writeFileSync(this.cachePath, JSON.stringify(index, null, 2));
this.index = index;
}
/**
* Fetch skills from a single source
*/
async fetchSource(source: SkillSource): Promise<MarketplaceSkill[]> {
const skills: MarketplaceSkill[] = [];
const branch = source.branch || 'main';
try {
// Try to fetch skills index file
const indexPaths = [
source.indexPath,
'skills.json',
'index.json',
'.skillkit/skills.json',
].filter(Boolean) as string[];
for (const indexPath of indexPaths) {
try {
const url = `https://raw.githubusercontent.com/${source.owner}/${source.repo}/${branch}/${indexPath}`;
const response = await fetch(url);
if (response.ok) {
const data = (await response.json()) as unknown;
if (Array.isArray(data)) {
for (const item of data) {
skills.push(this.parseSkillEntry(item as Record<string, unknown>, source));
}
return skills;
}
const dataObj = data as Record<string, unknown>;
if (dataObj.skills && Array.isArray(dataObj.skills)) {
for (const item of dataObj.skills) {
skills.push(this.parseSkillEntry(item as Record<string, unknown>, source));
}
return skills;
}
}
} catch {
// Try next path
}
}
// Fallback: Try to parse README for skill links
const readmeUrl = `https://raw.githubusercontent.com/${source.owner}/${source.repo}/${branch}/README.md`;
const readmeResponse = await fetch(readmeUrl);
if (readmeResponse.ok) {
const readme = await readmeResponse.text();
const parsedSkills = this.parseReadmeForSkills(readme, source);
skills.push(...parsedSkills);
}
// If still no skills, add the repo itself as a skill source
if (skills.length === 0) {
skills.push({
id: `${source.owner}/${source.repo}`,
name: source.repo,
description: source.description || `Skills from ${source.name}`,
source,
path: '/',
tags: ['repository'],
rawUrl: `https://github.com/${source.owner}/${source.repo}`,
});
}
} catch (error) {
console.error(`Failed to fetch skills from ${source.owner}/${source.repo}:`, error);
}
return skills;
}
/**
* Check if a path is an absolute URL
*/
private isAbsoluteUrl(path: string): boolean {
return /^https?:\/\//i.test(path);
}
/**
* Convert a GitHub URL to raw content URL
*/
private toRawUrl(url: string): string {
return url
.replace('://github.com/', '://raw.githubusercontent.com/')
.replace('/blob/', '/');
}
/**
* Parse a skill entry from JSON
*/
private parseSkillEntry(
item: Record<string, unknown>,
source: SkillSource
): MarketplaceSkill {
const name = String(item.name || item.title || 'Unknown');
const path = String(item.path || item.file || item.url || '/');
// Handle absolute URLs - use them directly instead of building from source
const rawUrl = this.isAbsoluteUrl(path)
? this.toRawUrl(path)
: this.buildRawUrl(source, path);
return {
id: `${source.owner}/${source.repo}/${path}`,
name,
description: String(item.description || item.desc || ''),
source,
path,
version: item.version as string | undefined,
author: item.author as string | undefined,
tags: Array.isArray(item.tags) ? item.tags : [],
agents: Array.isArray(item.agents) ? item.agents : undefined,
stars: typeof item.stars === 'number' ? item.stars : undefined,
updatedAt: item.updatedAt as string | undefined,
downloads: typeof item.downloads === 'number' ? item.downloads : undefined,
rawUrl,
};
}
/**
* Parse README for skill links
*/
private parseReadmeForSkills(
readme: string,
source: SkillSource
): MarketplaceSkill[] {
const skills: MarketplaceSkill[] = [];
const branch = source.branch || 'main';
// Look for markdown links to skill files
const linkPattern = /\[([^\]]+)\]\(([^)]+\.md)\)/g;
let match;
while ((match = linkPattern.exec(readme)) !== null) {
const name = match[1];
const path = match[2];
// Skip external links and non-skill files
if (path.startsWith('http') && !path.includes(source.repo)) {
continue;
}
// Extract description from surrounding text
const contextStart = Math.max(0, match.index - 200);
const contextEnd = Math.min(readme.length, match.index + 200);
const context = readme.slice(contextStart, contextEnd);
// Try to find description in list item or paragraph
const descMatch = context.match(/[-*]\s*\[.*?\]\(.*?\)\s*[-:]\s*(.+?)(?:\n|$)/);
const description = descMatch ? descMatch[1].trim() : '';
// Handle absolute URLs in README links
const isAbsolute = this.isAbsoluteUrl(path);
const normalizedPath = isAbsolute ? path : (path.startsWith('/') ? path : `/${path}`);
const rawUrl = isAbsolute
? this.toRawUrl(path)
: `https://raw.githubusercontent.com/${source.owner}/${source.repo}/${branch}/${path}`;
skills.push({
id: `${source.owner}/${source.repo}/${path}`,
name,
description,
source,
path: normalizedPath,
tags: this.inferTags(name, description),
rawUrl,
});
}
return skills;
}
/**
* Build raw URL for a skill
*/
private buildRawUrl(source: SkillSource, path: string): string {
const branch = source.branch || 'main';
const cleanPath = path.startsWith('/') ? path.slice(1) : path;
return `https://raw.githubusercontent.com/${source.owner}/${source.repo}/${branch}/${cleanPath}`;
}
/**
* Infer tags from name and description
*/
private inferTags(name: string, description: string): string[] {
const tags: string[] = [];
const text = `${name} ${description}`.toLowerCase();
const tagKeywords: Record<string, string[]> = {
typescript: ['typescript', 'ts', 'tsc'],
javascript: ['javascript', 'js', 'node'],
react: ['react', 'jsx', 'tsx'],
nextjs: ['next', 'nextjs', 'next.js'],
testing: ['test', 'jest', 'vitest', 'mocha'],
linting: ['lint', 'eslint', 'prettier'],
auth: ['auth', 'authentication', 'login', 'oauth'],
database: ['database', 'db', 'postgres', 'mysql', 'mongo'],
api: ['api', 'rest', 'graphql'],
devops: ['ci', 'cd', 'docker', 'kubernetes'],
git: ['git', 'github', 'commit'],
};
for (const [tag, keywords] of Object.entries(tagKeywords)) {
if (keywords.some((k) => text.includes(k))) {
tags.push(tag);
}
}
return tags;
}
/**
* Refresh the marketplace index
*/
async refresh(): Promise<MarketplaceIndex> {
const sources = this.getSources();
const allSkills: MarketplaceSkill[] = [];
// Fetch from all sources in parallel
const results = await Promise.all(
sources.map((source) => this.fetchSource(source))
);
for (const skills of results) {
allSkills.push(...skills);
}
// Create index
const index: MarketplaceIndex = {
version: 1,
updatedAt: new Date().toISOString(),
sources,
skills: allSkills,
totalCount: allSkills.length,
};
// Save to cache
this.saveCache(index);
return index;
}
/**
* Get the marketplace index (from cache or refresh)
*/
async getIndex(forceRefresh = false): Promise<MarketplaceIndex> {
// Check in-memory cache first
if (!forceRefresh && this.index) {
return this.index;
}
// Check file cache
if (!forceRefresh) {
const cached = this.loadCache();
if (cached) {
return cached;
}
}
return this.refresh();
}
/**
* Search the marketplace
*/
async search(options: MarketplaceSearchOptions = {}): Promise<MarketplaceSearchResult> {
const index = await this.getIndex();
let skills = [...index.skills];
// Filter by query
if (options.query) {
const query = options.query.toLowerCase();
skills = skills.filter(
(s) =>
s.name.toLowerCase().includes(query) ||
s.description.toLowerCase().includes(query) ||
s.tags.some((t) => t.toLowerCase().includes(query))
);
}
// Filter by tags
if (options.tags && options.tags.length > 0) {
skills = skills.filter((s) =>
options.tags!.some((t) => s.tags.includes(t))
);
}
// Filter by source
if (options.source) {
skills = skills.filter(
(s) =>
s.source.name === options.source ||
`${s.source.owner}/${s.source.repo}` === options.source
);
}
// Filter by agent
if (options.agent) {
skills = skills.filter(
(s) => !s.agents || s.agents.includes(options.agent!)
);
}
// Sort
const sortBy = options.sortBy || 'name';
const sortOrder = options.sortOrder || 'asc';
skills.sort((a, b) => {
let comparison = 0;
switch (sortBy) {
case 'name':
comparison = a.name.localeCompare(b.name);
break;
case 'stars':
comparison = (a.stars || 0) - (b.stars || 0);
break;
case 'downloads':
comparison = (a.downloads || 0) - (b.downloads || 0);
break;
case 'updatedAt':
comparison =
new Date(a.updatedAt || 0).getTime() -
new Date(b.updatedAt || 0).getTime();
break;
}
return sortOrder === 'desc' ? -comparison : comparison;
});
const total = skills.length;
// Apply pagination
if (options.offset) {
skills = skills.slice(options.offset);
}
if (options.limit) {
skills = skills.slice(0, options.limit);
}
return {
skills,
total,
query: options.query,
};
}
/**
* Get a skill by ID
*/
async getSkill(id: string): Promise<MarketplaceSkill | null> {
const index = await this.getIndex();
return index.skills.find((s) => s.id === id) || null;
}
/**
* Get skill content
*/
async getSkillContent(skill: MarketplaceSkill): Promise<string | null> {
if (!skill.rawUrl) {
return null;
}
try {
const response = await fetch(skill.rawUrl);
if (response.ok) {
return response.text();
}
} catch {
// Fetch failed
}
return null;
}
/**
* Get popular tags
*/
async getPopularTags(limit = 20): Promise<{ tag: string; count: number }[]> {
const index = await this.getIndex();
const tagCounts = new Map<string, number>();
for (const skill of index.skills) {
for (const tag of skill.tags) {
tagCounts.set(tag, (tagCounts.get(tag) || 0) + 1);
}
}
const tags = Array.from(tagCounts.entries())
.map(([tag, count]) => ({ tag, count }))
.sort((a, b) => b.count - a.count)
.slice(0, limit);
return tags;
}
/**
* Add a custom source
*/
addSource(source: SkillSource): void {
if (!this.config.sources) {
this.config.sources = [];
}
this.config.sources.push(source);
this.clearCache();
}
/**
* Remove a custom source
*/
removeSource(owner: string, repo: string): void {
if (this.config.sources) {
this.config.sources = this.config.sources.filter(
(s) => s.owner !== owner || s.repo !== repo
);
}
this.clearCache();
}
/**
* Clear cache
*/
clearCache(): void {
if (existsSync(this.cachePath)) {
unlinkSync(this.cachePath);
}
this.index = null;
}
}
/**
* Create a marketplace aggregator
*/
export function createMarketplaceAggregator(
config?: MarketplaceConfig
): MarketplaceAggregator {
return new MarketplaceAggregator(config);
}
+41
View File
@@ -0,0 +1,41 @@
/**
* Skill Marketplace Module
*
* Provides aggregated skill discovery from multiple GitHub repositories.
*
* @example
* ```typescript
* import { createMarketplaceAggregator } from '@skillkit/core';
*
* const marketplace = createMarketplaceAggregator();
*
* // Search for skills
* const results = await marketplace.search({ query: 'typescript' });
*
* // Get popular tags
* const tags = await marketplace.getPopularTags();
*
* // Refresh index from all sources
* await marketplace.refresh();
* ```
*/
export * from './types.js';
export * from './aggregator.js';
export {
MarketplaceAggregator,
createMarketplaceAggregator,
} from './aggregator.js';
export {
DEFAULT_SKILL_SOURCES,
MARKETPLACE_CACHE_FILE,
DEFAULT_CACHE_TTL,
type SkillSource,
type MarketplaceSkill,
type MarketplaceIndex,
type MarketplaceSearchOptions,
type MarketplaceSearchResult,
type MarketplaceConfig,
} from './types.js';
+153
View File
@@ -0,0 +1,153 @@
/**
* Skill Marketplace Types
*
* Types for the aggregated skill marketplace.
*/
/**
* Skill source repository
*/
export interface SkillSource {
/** Repository owner */
owner: string;
/** Repository name */
repo: string;
/** Human-readable name */
name: string;
/** Description */
description?: string;
/** Whether this is an official source */
official?: boolean;
/** Branch to fetch from */
branch?: string;
/** Path to skills index file */
indexPath?: string;
}
/**
* Skill entry in the marketplace
*/
export interface MarketplaceSkill {
/** Unique identifier (owner/repo/path) */
id: string;
/** Skill name */
name: string;
/** Description */
description: string;
/** Source repository */
source: SkillSource;
/** Path within the repository */
path: string;
/** Version if available */
version?: string;
/** Author */
author?: string;
/** Tags for categorization */
tags: string[];
/** Supported agents */
agents?: string[];
/** GitHub stars (if available) */
stars?: number;
/** Last updated date */
updatedAt?: string;
/** Download/install count */
downloads?: number;
/** Raw content URL */
rawUrl?: string;
}
/**
* Marketplace index (cached locally)
*/
export interface MarketplaceIndex {
/** Index version */
version: number;
/** When the index was last updated */
updatedAt: string;
/** Sources included in this index */
sources: SkillSource[];
/** All skills in the index */
skills: MarketplaceSkill[];
/** Total skill count */
totalCount: number;
}
/**
* Search options for the marketplace
*/
export interface MarketplaceSearchOptions {
/** Search query */
query?: string;
/** Filter by tags */
tags?: string[];
/** Filter by source */
source?: string;
/** Filter by agent compatibility */
agent?: string;
/** Sort by field */
sortBy?: 'name' | 'stars' | 'downloads' | 'updatedAt';
/** Sort direction */
sortOrder?: 'asc' | 'desc';
/** Limit results */
limit?: number;
/** Offset for pagination */
offset?: number;
}
/**
* Search result
*/
export interface MarketplaceSearchResult {
/** Matching skills */
skills: MarketplaceSkill[];
/** Total matches (before limit) */
total: number;
/** Query that was searched */
query?: string;
}
/**
* Marketplace configuration
*/
export interface MarketplaceConfig {
/** Custom sources to include */
sources?: SkillSource[];
/** Cache directory */
cacheDir?: string;
/** Cache TTL in milliseconds */
cacheTTL?: number;
/** GitHub token for API access */
githubToken?: string;
}
/**
* Default skill sources
*/
export const DEFAULT_SKILL_SOURCES: SkillSource[] = [
{
owner: 'composioHQ',
repo: 'awesome-claude-code-skills',
name: 'Composio Curated',
description: 'Curated collection of Claude Code skills',
official: false,
branch: 'main',
},
{
owner: 'anthropics',
repo: 'courses',
name: 'Anthropic Official',
description: 'Official Anthropic courses and skills',
official: true,
branch: 'master',
},
];
/**
* Cache file name
*/
export const MARKETPLACE_CACHE_FILE = 'marketplace-index.json';
/**
* Default cache TTL (1 hour)
*/
export const DEFAULT_CACHE_TTL = 60 * 60 * 1000;
@@ -0,0 +1,500 @@
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import {
RuleBasedCompressor,
APIBasedCompressor,
MemoryCompressor,
LearningConsolidator,
createRuleBasedCompressor,
createAPIBasedCompressor,
createMemoryCompressor,
} from '../compressor.js';
import type { Observation, Learning } from '../types.js';
vi.mock('node:fs', () => ({
existsSync: vi.fn(),
readFileSync: vi.fn(),
writeFileSync: vi.fn(),
mkdirSync: vi.fn(),
}));
// Helper to create mock observations
const createObservation = (overrides: Partial<Observation> = {}): Observation => ({
id: `obs-${Math.random().toString(36).slice(2, 9)}`,
timestamp: new Date().toISOString(),
sessionId: 'test-session',
agent: 'claude-code',
type: 'tool_use',
content: {
action: 'Test action',
context: 'Test context',
},
relevance: 60,
...overrides,
});
// Helper to create mock learnings
const createLearning = (overrides: Partial<Learning> = {}): Learning => ({
id: `learn-${Math.random().toString(36).slice(2, 9)}`,
createdAt: new Date().toISOString(),
updatedAt: new Date().toISOString(),
source: 'session',
title: 'Test Learning',
content: 'Test content for learning',
scope: 'project',
tags: ['test'],
useCount: 0,
...overrides,
});
describe('RuleBasedCompressor', () => {
let compressor: RuleBasedCompressor;
beforeEach(() => {
compressor = new RuleBasedCompressor();
vi.clearAllMocks();
});
describe('getType', () => {
it('should return rule-based', () => {
expect(compressor.getType()).toBe('rule-based');
});
});
describe('compress', () => {
it('should return empty result when observations below threshold', async () => {
const observations = [createObservation(), createObservation()];
const result = await compressor.compress(observations, { minObservations: 5 });
expect(result.learnings).toHaveLength(0);
expect(result.skippedObservationIds).toHaveLength(2);
});
it('should extract error-solution pairs', async () => {
const observations = [
createObservation({
type: 'error',
content: {
action: 'Build failed',
context: 'Running npm build',
error: 'TypeError: Cannot read property of undefined',
},
relevance: 85,
}),
createObservation({
type: 'solution',
content: {
action: 'Added null check',
context: 'Fixed the TypeError',
solution: 'Added optional chaining operator',
},
relevance: 90,
}),
createObservation({
type: 'tool_use',
content: {
action: 'Some other action',
context: 'Context',
},
relevance: 50,
}),
];
const result = await compressor.compress(observations, { minObservations: 2 });
expect(result.learnings.length).toBeGreaterThanOrEqual(1);
const errorSolutionLearning = result.learnings.find((l) =>
l.title.includes('Error Resolution')
);
expect(errorSolutionLearning).toBeDefined();
});
it('should extract decision patterns', async () => {
const observations = [
createObservation({
type: 'decision',
content: {
action: 'Use TypeScript',
context: 'Choosing programming language',
},
relevance: 75,
}),
createObservation({
type: 'decision',
content: {
action: 'Use React hooks',
context: 'State management approach',
},
relevance: 75,
}),
createObservation({
type: 'tool_use',
content: {
action: 'Filler',
context: 'Context',
},
relevance: 50,
}),
];
const result = await compressor.compress(observations, { minObservations: 2 });
expect(result.learnings.length).toBeGreaterThanOrEqual(1);
const decisionLearning = result.learnings.find((l) => l.title.includes('Decision'));
expect(decisionLearning).toBeDefined();
});
it('should filter by minimum importance', async () => {
const observations = [
createObservation({
type: 'tool_use',
content: { action: 'Low importance action', context: 'Context' },
relevance: 50,
}),
createObservation({
type: 'tool_use',
content: { action: 'Another action', context: 'Context' },
relevance: 50,
}),
createObservation({
type: 'tool_use',
content: { action: 'Third action', context: 'Context' },
relevance: 50,
}),
];
const result = await compressor.compress(observations, {
minObservations: 2,
minImportance: 9, // Very high threshold
});
// Tool use patterns have low importance, so should be filtered
expect(result.learnings.length).toBe(0);
});
it('should limit output to maxLearnings', async () => {
const observations = [
createObservation({
type: 'error',
content: { action: 'Error 1', context: 'Context', error: 'Error 1' },
relevance: 85,
}),
createObservation({
type: 'error',
content: { action: 'Error 2', context: 'Context', error: 'Error 2' },
relevance: 85,
}),
createObservation({
type: 'error',
content: { action: 'Error 3', context: 'Context', error: 'Error 3' },
relevance: 85,
}),
createObservation({
type: 'solution',
content: { action: 'Solution 1', context: 'Context', solution: 'Solution' },
relevance: 90,
}),
];
const result = await compressor.compress(observations, {
minObservations: 2,
maxLearnings: 2,
});
expect(result.learnings.length).toBeLessThanOrEqual(2);
});
it('should add additional tags to learnings', async () => {
const observations = [
createObservation({
type: 'error',
content: { action: 'Error', context: 'Context', error: 'Some error' },
relevance: 85,
}),
createObservation({
type: 'solution',
content: { action: 'Fix', context: 'Context', solution: 'Fixed it' },
relevance: 90,
}),
createObservation({
type: 'tool_use',
content: { action: 'Action', context: 'Context' },
relevance: 50,
}),
];
const result = await compressor.compress(observations, {
minObservations: 2,
additionalTags: ['project-x', 'sprint-1'],
});
if (result.learnings.length > 0) {
expect(result.learnings[0].tags).toContain('project-x');
expect(result.learnings[0].tags).toContain('sprint-1');
}
});
it('should calculate compression stats', async () => {
const observations = [
createObservation({ type: 'error', relevance: 85 }),
createObservation({ type: 'solution', relevance: 90 }),
createObservation({ type: 'tool_use', relevance: 50 }),
];
const result = await compressor.compress(observations, { minObservations: 2 });
expect(result.stats.inputCount).toBe(3);
expect(result.stats.outputCount).toBe(result.learnings.length);
expect(result.stats.compressionRatio).toBeDefined();
});
});
});
describe('APIBasedCompressor', () => {
let compressor: APIBasedCompressor;
beforeEach(() => {
compressor = new APIBasedCompressor({
provider: 'anthropic',
apiKey: 'test-key',
model: 'claude-3-haiku-20240307',
});
vi.clearAllMocks();
});
describe('getType', () => {
it('should return api', () => {
expect(compressor.getType()).toBe('api');
});
});
describe('compress', () => {
it('should return empty result when observations below threshold', async () => {
const observations = [createObservation()];
const result = await compressor.compress(observations, { minObservations: 5 });
expect(result.learnings).toHaveLength(0);
});
it('should fall back to rule-based on API failure', async () => {
// Mock fetch to fail
global.fetch = vi.fn().mockRejectedValue(new Error('API error'));
const observations = [
createObservation({ type: 'error', relevance: 85 }),
createObservation({ type: 'solution', relevance: 90 }),
createObservation({ type: 'tool_use', relevance: 50 }),
];
const result = await compressor.compress(observations, { minObservations: 2 });
// Should not throw, should return result from fallback
expect(result.stats.inputCount).toBe(3);
});
});
});
describe('MemoryCompressor', () => {
beforeEach(() => {
vi.clearAllMocks();
vi.mocked(existsSync).mockReturnValue(false);
});
describe('constructor', () => {
it('should create with default engine', () => {
const compressor = new MemoryCompressor('/test/project');
expect(compressor.getEngineType()).toBe('rule-based');
});
it('should accept custom engine', () => {
const apiEngine = new APIBasedCompressor({
provider: 'openai',
apiKey: 'test',
});
const compressor = new MemoryCompressor('/test/project', { engine: apiEngine });
expect(compressor.getEngineType()).toBe('api');
});
});
describe('setEngine', () => {
it('should allow changing the engine', () => {
const compressor = new MemoryCompressor('/test/project');
expect(compressor.getEngineType()).toBe('rule-based');
compressor.setEngine(
new APIBasedCompressor({
provider: 'anthropic',
apiKey: 'test',
})
);
expect(compressor.getEngineType()).toBe('api');
});
});
describe('compressAndStore', () => {
it('should compress and store learnings', async () => {
const compressor = createMemoryCompressor('/test/project', {
projectName: 'test-project',
});
const observations = [
createObservation({
type: 'error',
content: { action: 'Error', context: 'Context', error: 'Test error' },
relevance: 85,
}),
createObservation({
type: 'solution',
content: { action: 'Fix', context: 'Fixed error', solution: 'Applied fix' },
relevance: 90,
}),
createObservation({ type: 'tool_use', relevance: 50 }),
];
const { learnings, result } = await compressor.compressAndStore(observations, {
minObservations: 2,
});
expect(result.stats.inputCount).toBe(3);
// Learnings should have been created
expect(learnings.length).toBe(result.learnings.length);
});
});
});
describe('LearningConsolidator', () => {
let consolidator: LearningConsolidator;
beforeEach(() => {
consolidator = new LearningConsolidator();
vi.clearAllMocks();
vi.mocked(existsSync).mockReturnValue(false);
});
describe('findSimilar', () => {
it('should find similar learnings', () => {
const learnings = [
createLearning({
id: 'l1',
title: 'React hooks best practices',
tags: ['react', 'hooks'],
patterns: ['best-practices'],
content: 'When using React hooks, always follow the rules of hooks.',
}),
createLearning({
id: 'l2',
title: 'React hooks patterns',
tags: ['react', 'hooks', 'patterns'],
patterns: ['best-practices'],
content: 'React hooks provide a way to use state in functional components.',
}),
createLearning({
id: 'l3',
title: 'TypeScript generics guide',
tags: ['typescript', 'generics'],
patterns: ['type-safety'],
content: 'TypeScript generics allow you to write reusable type-safe code.',
}),
];
const pairs = consolidator.findSimilar(learnings, 0.5);
// The two React hooks learnings should be similar
expect(pairs.length).toBeGreaterThanOrEqual(1);
const reactPair = pairs.find(
([a, b]) =>
(a.id === 'l1' && b.id === 'l2') || (a.id === 'l2' && b.id === 'l1')
);
expect(reactPair).toBeDefined();
});
it('should not find similar for distinct learnings', () => {
const learnings = [
createLearning({
title: 'React tutorial',
tags: ['react', 'frontend'],
content: 'React is a library for building user interfaces.',
}),
createLearning({
title: 'Python basics',
tags: ['python', 'backend'],
content: 'Python is a versatile programming language.',
}),
];
const pairs = consolidator.findSimilar(learnings, 0.8);
expect(pairs).toHaveLength(0);
});
});
describe('merge', () => {
it('should merge two learnings', () => {
const l1 = createLearning({
title: 'React hooks patterns',
content: 'Content 1 about hooks',
tags: ['react', 'hooks'],
frameworks: ['react'],
patterns: ['hooks'],
useCount: 5,
effectiveness: 80,
});
const l2 = createLearning({
title: 'React hooks best practices',
content: 'Content 2 about best practices for hooks in React applications',
tags: ['react', 'best-practices'],
frameworks: ['react', 'nextjs'],
patterns: ['hooks', 'state-management'],
useCount: 3,
effectiveness: 70,
});
const merged = consolidator.merge(l1, l2);
// Should combine tags
expect(merged.tags).toContain('react');
expect(merged.tags).toContain('hooks');
expect(merged.tags).toContain('best-practices');
// Should combine frameworks
expect(merged.frameworks).toContain('react');
expect(merged.frameworks).toContain('nextjs');
// Should combine patterns
expect(merged.patterns).toContain('hooks');
expect(merged.patterns).toContain('state-management');
// Should combine use count
expect(merged.useCount).toBe(8);
// Should keep higher effectiveness
expect(merged.effectiveness).toBe(80);
});
});
});
describe('Factory functions', () => {
it('createRuleBasedCompressor should create instance', () => {
const compressor = createRuleBasedCompressor();
expect(compressor).toBeInstanceOf(RuleBasedCompressor);
expect(compressor.getType()).toBe('rule-based');
});
it('createAPIBasedCompressor should create instance', () => {
const compressor = createAPIBasedCompressor({
provider: 'anthropic',
apiKey: 'test-key',
});
expect(compressor).toBeInstanceOf(APIBasedCompressor);
expect(compressor.getType()).toBe('api');
});
it('createMemoryCompressor should create instance', () => {
vi.mocked(existsSync).mockReturnValue(false);
const compressor = createMemoryCompressor('/test/project');
expect(compressor).toBeInstanceOf(MemoryCompressor);
});
});
@@ -0,0 +1,533 @@
import { describe, it, expect, beforeEach, vi } from 'vitest';
import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { MemoryInjector, createMemoryInjector } from '../injector.js';
import type { Learning } from '../types.js';
import type { ProjectContext } from '../../context/types.js';
vi.mock('node:fs', () => ({
existsSync: vi.fn(),
readFileSync: vi.fn(),
writeFileSync: vi.fn(),
mkdirSync: vi.fn(),
}));
// Helper to create mock learnings
const createLearning = (overrides: Partial<Learning> = {}): Learning => ({
id: `learn-${Math.random().toString(36).slice(2, 9)}`,
createdAt: new Date().toISOString(),
updatedAt: new Date().toISOString(),
source: 'session',
title: 'Test Learning',
content: 'Test content for learning that provides useful information about best practices.',
scope: 'project',
tags: ['test'],
useCount: 0,
...overrides,
});
// Helper to create mock project context
const createProjectContext = (overrides: Partial<ProjectContext> = {}): ProjectContext => ({
version: 1,
project: {
name: 'test-project',
description: 'A test project',
type: 'web-app',
},
stack: {
languages: [{ name: 'TypeScript', confidence: 100 }],
frameworks: [{ name: 'React', confidence: 100 }, { name: 'Next.js', confidence: 90 }],
libraries: [],
styling: [{ name: 'Tailwind', confidence: 100 }],
testing: [{ name: 'Vitest', confidence: 100 }],
databases: [],
tools: [],
runtime: [{ name: 'Node.js', confidence: 100 }],
},
...overrides,
});
// Mock YAML content for project learnings
const createMockLearningsYaml = (learnings: Learning[]) => ({
version: 1,
learnings,
});
describe('MemoryInjector', () => {
let injector: MemoryInjector;
beforeEach(() => {
vi.clearAllMocks();
vi.mocked(existsSync).mockReturnValue(false);
});
describe('constructor', () => {
it('should create instance without project context', () => {
injector = new MemoryInjector('/test/project');
expect(injector).toBeInstanceOf(MemoryInjector);
});
it('should create instance with project context', () => {
const context = createProjectContext();
injector = new MemoryInjector('/test/project', 'test-project', context);
expect(injector).toBeInstanceOf(MemoryInjector);
});
});
describe('setProjectContext', () => {
it('should set project context', () => {
injector = new MemoryInjector('/test/project');
const context = createProjectContext();
injector.setProjectContext(context);
// No direct way to verify, but it should not throw
});
});
describe('getRelevantMemories', () => {
it('should return empty array when no learnings exist', async () => {
injector = new MemoryInjector('/test/project');
const memories = await injector.getRelevantMemories();
expect(memories).toHaveLength(0);
});
it('should return learnings with relevance scores', async () => {
const learnings = [
createLearning({
id: 'l1',
title: 'React hooks best practices',
tags: ['react', 'hooks'],
frameworks: ['react'],
useCount: 5,
}),
];
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(
JSON.stringify(createMockLearningsYaml(learnings))
);
const context = createProjectContext();
injector = new MemoryInjector('/test/project', 'test-project', context);
const memories = await injector.getRelevantMemories();
expect(memories.length).toBeGreaterThanOrEqual(0);
});
it('should filter by minimum relevance', async () => {
const learnings = [
createLearning({
id: 'l1',
title: 'Unrelated learning',
tags: ['unrelated'],
useCount: 0,
}),
];
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(
JSON.stringify(createMockLearningsYaml(learnings))
);
injector = new MemoryInjector('/test/project');
const memories = await injector.getRelevantMemories({ minRelevance: 90 });
expect(memories).toHaveLength(0);
});
it('should limit results to maxLearnings', async () => {
const learnings = Array.from({ length: 20 }, (_, i) =>
createLearning({
id: `l${i}`,
title: `Learning ${i}`,
tags: ['common-tag'],
useCount: i,
})
);
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(
JSON.stringify(createMockLearningsYaml(learnings))
);
injector = new MemoryInjector('/test/project');
const memories = await injector.getRelevantMemories({
maxLearnings: 5,
minRelevance: 0,
});
expect(memories.length).toBeLessThanOrEqual(5);
});
it('should match by current task keywords', async () => {
const learnings = [
createLearning({
id: 'l1',
title: 'Authentication patterns',
content: 'How to implement JWT authentication in Node.js applications.',
tags: ['auth', 'jwt', 'security'],
}),
createLearning({
id: 'l2',
title: 'CSS Grid layout',
content: 'Guide to using CSS Grid for responsive layouts.',
tags: ['css', 'layout'],
}),
];
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(
JSON.stringify(createMockLearningsYaml(learnings))
);
injector = new MemoryInjector('/test/project');
const memories = await injector.getRelevantMemories({
currentTask: 'implement JWT authentication',
minRelevance: 0,
});
// Auth learning should rank higher
if (memories.length > 0) {
const authMemory = memories.find((m) => m.learning.id === 'l1');
const cssMemory = memories.find((m) => m.learning.id === 'l2');
if (authMemory && cssMemory) {
expect(authMemory.relevanceScore).toBeGreaterThan(cssMemory.relevanceScore);
}
}
});
});
describe('inject', () => {
it('should return empty result when no learnings exist', async () => {
injector = new MemoryInjector('/test/project');
const result = await injector.inject();
expect(result.memories).toHaveLength(0);
expect(result.formattedContent).toBe('');
expect(result.totalTokens).toBe(0);
expect(result.stats.injected).toBe(0);
});
it('should respect token budget', async () => {
const learnings = Array.from({ length: 10 }, (_, i) =>
createLearning({
id: `l${i}`,
title: `Learning ${i}`,
content: 'A'.repeat(500), // Long content
tags: ['test'],
useCount: 10 - i,
})
);
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(
JSON.stringify(createMockLearningsYaml(learnings))
);
injector = new MemoryInjector('/test/project');
const result = await injector.inject({
maxTokens: 100,
minRelevance: 0,
});
expect(result.totalTokens).toBeLessThanOrEqual(100);
});
it('should format content as markdown by default', async () => {
const learnings = [
createLearning({
id: 'l1',
title: 'Test Learning',
content: 'Test content',
tags: ['test'],
useCount: 5,
}),
];
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(
JSON.stringify(createMockLearningsYaml(learnings))
);
injector = new MemoryInjector('/test/project');
const result = await injector.inject({ minRelevance: 0 });
if (result.memories.length > 0) {
expect(result.formattedContent).toContain('# Relevant Memories');
expect(result.formattedContent).toContain('## Test Learning');
}
});
});
describe('injectForAgent', () => {
const learnings = [
createLearning({
id: 'l1',
title: 'Test Learning',
content: 'Test content for agent',
tags: ['test'],
frameworks: ['react'],
useCount: 5,
}),
];
beforeEach(() => {
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(
JSON.stringify(createMockLearningsYaml(learnings))
);
});
it('should format for claude-code with XML tags', async () => {
injector = new MemoryInjector('/test/project');
const result = await injector.injectForAgent('claude-code', { minRelevance: 0 });
if (result.memories.length > 0) {
expect(result.formattedContent).toContain('<memories>');
expect(result.formattedContent).toContain('<memory');
expect(result.formattedContent).toContain('</memories>');
}
});
it('should format for cursor with MDC format', async () => {
injector = new MemoryInjector('/test/project');
const result = await injector.injectForAgent('cursor', { minRelevance: 0 });
if (result.memories.length > 0) {
expect(result.formattedContent).toContain('---');
expect(result.formattedContent).toContain('description:');
expect(result.formattedContent).toContain('# Session Memories');
}
});
it('should format for github-copilot with HTML comments', async () => {
injector = new MemoryInjector('/test/project');
const result = await injector.injectForAgent('github-copilot', { minRelevance: 0 });
if (result.memories.length > 0) {
expect(result.formattedContent).toContain('<!-- Session Memories -->');
}
});
it('should use default markdown for unknown agents', async () => {
injector = new MemoryInjector('/test/project');
const result = await injector.injectForAgent('universal', { minRelevance: 0 });
if (result.memories.length > 0) {
expect(result.formattedContent).toContain('# Relevant Memories');
}
});
});
describe('getSummaries', () => {
it('should return memory summaries', () => {
const learnings = [
createLearning({
id: 'l1',
title: 'Test Learning',
tags: ['test', 'example'],
}),
];
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(
JSON.stringify(createMockLearningsYaml(learnings))
);
injector = new MemoryInjector('/test/project');
const summaries = injector.getSummaries();
expect(summaries.length).toBeGreaterThanOrEqual(0);
if (summaries.length > 0) {
expect(summaries[0]).toHaveProperty('id');
expect(summaries[0]).toHaveProperty('title');
expect(summaries[0]).toHaveProperty('tags');
expect(summaries[0]).toHaveProperty('relevance');
}
});
});
describe('getPreviews', () => {
it('should return memory previews for given IDs', () => {
const learnings = [
createLearning({
id: 'l1',
title: 'Test Learning',
content: 'Full content that is longer than the excerpt limit would allow.',
tags: ['test'],
}),
];
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(
JSON.stringify(createMockLearningsYaml(learnings))
);
injector = new MemoryInjector('/test/project');
const previews = injector.getPreviews(['l1']);
if (previews.length > 0) {
expect(previews[0]).toHaveProperty('excerpt');
expect(previews[0].excerpt.length).toBeLessThanOrEqual(200);
}
});
it('should return empty for non-existent IDs', () => {
vi.mocked(existsSync).mockReturnValue(false);
injector = new MemoryInjector('/test/project');
const previews = injector.getPreviews(['non-existent']);
expect(previews).toHaveLength(0);
});
});
describe('getFullMemories', () => {
it('should return full memory content', () => {
const fullContent = 'This is the full content of the learning that should be returned.';
const learnings = [
createLearning({
id: 'l1',
title: 'Test Learning',
content: fullContent,
tags: ['test'],
}),
];
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(
JSON.stringify(createMockLearningsYaml(learnings))
);
injector = new MemoryInjector('/test/project');
const fullMemories = injector.getFullMemories(['l1']);
if (fullMemories.length > 0) {
expect(fullMemories[0].content).toBe(fullContent);
}
});
});
describe('search', () => {
it('should search memories by query', () => {
const learnings = [
createLearning({
id: 'l1',
title: 'React hooks patterns',
content: 'How to use useEffect and useState effectively.',
tags: ['react', 'hooks'],
}),
createLearning({
id: 'l2',
title: 'Python data analysis',
content: 'Using pandas for data manipulation.',
tags: ['python', 'data'],
}),
];
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(
JSON.stringify(createMockLearningsYaml(learnings))
);
injector = new MemoryInjector('/test/project');
const results = injector.search('react hooks');
// React learning should be found
const reactResult = results.find((r) => r.learning.id === 'l1');
if (results.length > 0 && reactResult) {
expect(reactResult.matchedBy.keywords.length).toBeGreaterThanOrEqual(0);
}
});
it('should respect minRelevance in search', () => {
const learnings = [
createLearning({
id: 'l1',
title: 'Unrelated topic',
content: 'Nothing to do with the search.',
tags: ['other'],
}),
];
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(
JSON.stringify(createMockLearningsYaml(learnings))
);
injector = new MemoryInjector('/test/project');
const results = injector.search('completely different query', { minRelevance: 80 });
expect(results).toHaveLength(0);
});
});
describe('formatForAgent', () => {
it('should escape XML special characters for Claude', () => {
const learnings = [
createLearning({
id: 'l1',
title: 'Test <script> & "quotes"',
content: 'Content with <tags> & special chars',
tags: ['test'],
useCount: 5,
}),
];
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(
JSON.stringify(createMockLearningsYaml(learnings))
);
injector = new MemoryInjector('/test/project');
const memories = injector.search('test', { minRelevance: 0 });
const formatted = injector.formatForAgent(memories, 'claude-code');
if (memories.length > 0) {
expect(formatted).toContain('&lt;script&gt;');
expect(formatted).toContain('&amp;');
expect(formatted).toContain('&quot;');
}
});
});
});
describe('createMemoryInjector', () => {
beforeEach(() => {
vi.clearAllMocks();
vi.mocked(existsSync).mockReturnValue(false);
});
it('should create MemoryInjector instance', () => {
const injector = createMemoryInjector('/test/project');
expect(injector).toBeInstanceOf(MemoryInjector);
});
it('should create with project name', () => {
const injector = createMemoryInjector('/test/project', 'my-project');
expect(injector).toBeInstanceOf(MemoryInjector);
});
it('should create with project context', () => {
const context = createProjectContext();
const injector = createMemoryInjector('/test/project', 'my-project', context);
expect(injector).toBeInstanceOf(MemoryInjector);
});
});
@@ -0,0 +1,647 @@
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { LearningStore } from '../learning-store.js';
import type { Learning } from '../types.js';
vi.mock('node:fs', () => ({
existsSync: vi.fn(),
readFileSync: vi.fn(),
writeFileSync: vi.fn(),
mkdirSync: vi.fn(),
}));
// Helper to check if a string is a valid UUID
const isValidUUID = (str: string): boolean => {
const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
return uuidRegex.test(str);
};
describe('LearningStore', () => {
beforeEach(() => {
vi.clearAllMocks();
vi.useFakeTimers();
vi.setSystemTime(new Date('2024-01-15T10:00:00Z'));
});
afterEach(() => {
vi.useRealTimers();
vi.resetAllMocks();
});
describe('constructor', () => {
it('should set project file path for project scope', () => {
vi.mocked(existsSync).mockReturnValue(false);
const store = new LearningStore('project', '/test/project', 'my-project');
expect(store.getScope()).toBe('project');
});
it('should set global file path for global scope', () => {
vi.mocked(existsSync).mockReturnValue(false);
const store = new LearningStore('global');
expect(store.getScope()).toBe('global');
});
});
describe('add', () => {
it('should add a new learning', () => {
vi.mocked(existsSync).mockReturnValue(false);
const store = new LearningStore('project', '/test/project', 'my-project');
const learning = store.add({
source: 'session',
title: 'React hooks best practices',
content: 'When using useEffect, always include cleanup functions...',
tags: ['react', 'hooks', 'best-practices'],
frameworks: ['react'],
});
expect(isValidUUID(learning.id)).toBe(true);
expect(learning).toMatchObject({
createdAt: '2024-01-15T10:00:00.000Z',
updatedAt: '2024-01-15T10:00:00.000Z',
source: 'session',
title: 'React hooks best practices',
useCount: 0,
scope: 'project',
project: 'my-project',
});
expect(vi.mocked(writeFileSync)).toHaveBeenCalled();
});
});
describe('update', () => {
it('should update an existing learning', () => {
const existingData = `
version: 1
learnings:
- id: learn-1
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: Original title
content: Original content
scope: project
tags:
- react
useCount: 5
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingData);
const store = new LearningStore('project', '/test/project');
const updated = store.update('learn-1', {
title: 'Updated title',
content: 'Updated content',
});
expect(updated).not.toBeNull();
expect(updated!.title).toBe('Updated title');
expect(updated!.content).toBe('Updated content');
expect(updated!.updatedAt).toBe('2024-01-15T10:00:00.000Z');
expect(updated!.useCount).toBe(5); // Preserved
});
it('should return null when learning not found', () => {
vi.mocked(existsSync).mockReturnValue(false);
const store = new LearningStore('project', '/test/project');
const updated = store.update('non-existent', { title: 'test' });
expect(updated).toBeNull();
});
});
describe('delete', () => {
it('should delete an existing learning', () => {
const existingData = `
version: 1
learnings:
- id: learn-1
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: To delete
content: Content
scope: project
tags: []
useCount: 0
- id: learn-2
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: To keep
content: Content
scope: project
tags: []
useCount: 0
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingData);
const store = new LearningStore('project', '/test/project');
const result = store.delete('learn-1');
expect(result).toBe(true);
expect(store.getAll()).toHaveLength(1);
expect(store.getAll()[0].id).toBe('learn-2');
});
it('should return false when learning not found', () => {
vi.mocked(existsSync).mockReturnValue(false);
const store = new LearningStore('project', '/test/project');
const result = store.delete('non-existent');
expect(result).toBe(false);
});
});
describe('getByTags', () => {
it('should find learnings by tags', () => {
const existingData = `
version: 1
learnings:
- id: learn-1
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: React patterns
content: Content
scope: project
tags:
- react
- patterns
useCount: 0
- id: learn-2
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: TypeScript tips
content: Content
scope: project
tags:
- typescript
- tips
useCount: 0
- id: learn-3
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: React TypeScript
content: Content
scope: project
tags:
- react
- typescript
useCount: 0
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingData);
const store = new LearningStore('project', '/test/project');
const results = store.getByTags(['react']);
expect(results).toHaveLength(2);
expect(results.map((l) => l.id)).toContain('learn-1');
expect(results.map((l) => l.id)).toContain('learn-3');
});
it('should be case-insensitive', () => {
const existingData = `
version: 1
learnings:
- id: learn-1
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: React patterns
content: Content
scope: project
tags:
- React
- PATTERNS
useCount: 0
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingData);
const store = new LearningStore('project', '/test/project');
const results = store.getByTags(['react', 'patterns']);
expect(results).toHaveLength(1);
});
});
describe('getByFrameworks', () => {
it('should find learnings by frameworks', () => {
const existingData = `
version: 1
learnings:
- id: learn-1
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: Next.js routing
content: Content
scope: project
tags: []
frameworks:
- nextjs
useCount: 0
- id: learn-2
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: Express middleware
content: Content
scope: project
tags: []
frameworks:
- express
useCount: 0
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingData);
const store = new LearningStore('project', '/test/project');
const results = store.getByFrameworks(['nextjs']);
expect(results).toHaveLength(1);
expect(results[0].title).toBe('Next.js routing');
});
});
describe('getRecent', () => {
it('should return most recently updated learnings', () => {
const existingData = `
version: 1
learnings:
- id: learn-1
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: Oldest
content: Content
scope: project
tags: []
useCount: 0
- id: learn-2
createdAt: "2024-01-12T09:00:00.000Z"
updatedAt: "2024-01-14T09:00:00.000Z"
source: session
title: Middle
content: Content
scope: project
tags: []
useCount: 0
- id: learn-3
createdAt: "2024-01-11T09:00:00.000Z"
updatedAt: "2024-01-15T09:00:00.000Z"
source: session
title: Newest
content: Content
scope: project
tags: []
useCount: 0
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingData);
const store = new LearningStore('project', '/test/project');
const results = store.getRecent(2);
expect(results).toHaveLength(2);
expect(results[0].title).toBe('Newest');
expect(results[1].title).toBe('Middle');
});
});
describe('getMostUsed', () => {
it('should return most used learnings', () => {
const existingData = `
version: 1
learnings:
- id: learn-1
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: Low usage
content: Content
scope: project
tags: []
useCount: 2
- id: learn-2
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: High usage
content: Content
scope: project
tags: []
useCount: 15
- id: learn-3
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: Medium usage
content: Content
scope: project
tags: []
useCount: 8
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingData);
const store = new LearningStore('project', '/test/project');
const results = store.getMostUsed(2);
expect(results).toHaveLength(2);
expect(results[0].title).toBe('High usage');
expect(results[1].title).toBe('Medium usage');
});
});
describe('getMostEffective', () => {
it('should return most effective learnings', () => {
const existingData = `
version: 1
learnings:
- id: learn-1
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: No rating
content: Content
scope: project
tags: []
useCount: 0
- id: learn-2
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: High effectiveness
content: Content
scope: project
tags: []
useCount: 0
effectiveness: 90
- id: learn-3
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: Low effectiveness
content: Content
scope: project
tags: []
useCount: 0
effectiveness: 40
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingData);
const store = new LearningStore('project', '/test/project');
const results = store.getMostEffective(2);
expect(results).toHaveLength(2);
expect(results[0].title).toBe('High effectiveness');
expect(results[1].title).toBe('Low effectiveness');
});
});
describe('incrementUseCount', () => {
it('should increment use count and set lastUsed', () => {
const existingData = `
version: 1
learnings:
- id: learn-1
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: Test
content: Content
scope: project
tags: []
useCount: 5
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingData);
const store = new LearningStore('project', '/test/project');
store.incrementUseCount('learn-1');
const learning = store.getById('learn-1');
expect(learning?.useCount).toBe(6);
expect(learning?.lastUsed).toBe('2024-01-15T10:00:00.000Z');
});
});
describe('setEffectiveness', () => {
it('should set effectiveness rating', () => {
const existingData = `
version: 1
learnings:
- id: learn-1
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: Test
content: Content
scope: project
tags: []
useCount: 0
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingData);
const store = new LearningStore('project', '/test/project');
store.setEffectiveness('learn-1', 85);
const learning = store.getById('learn-1');
expect(learning?.effectiveness).toBe(85);
});
it('should clamp effectiveness between 0 and 100', () => {
const existingData = `
version: 1
learnings:
- id: learn-1
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: Test
content: Content
scope: project
tags: []
useCount: 0
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingData);
const store = new LearningStore('project', '/test/project');
store.setEffectiveness('learn-1', 150);
expect(store.getById('learn-1')?.effectiveness).toBe(100);
store.setEffectiveness('learn-1', -20);
expect(store.getById('learn-1')?.effectiveness).toBe(0);
});
});
describe('search', () => {
it('should search by title', () => {
const existingData = `
version: 1
learnings:
- id: learn-1
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: React hooks patterns
content: Some content about hooks
scope: project
tags:
- react
useCount: 0
- id: learn-2
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: TypeScript generics
content: Generic types explained
scope: project
tags:
- typescript
useCount: 0
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingData);
const store = new LearningStore('project', '/test/project');
const results = store.search('React hooks');
expect(results).toHaveLength(1);
expect(results[0].title).toBe('React hooks patterns');
});
it('should search by content', () => {
const existingData = `
version: 1
learnings:
- id: learn-1
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: Error handling
content: Use try-catch blocks for async operations
scope: project
tags: []
useCount: 0
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingData);
const store = new LearningStore('project', '/test/project');
const results = store.search('async operations');
expect(results).toHaveLength(1);
});
it('should search by tags', () => {
const existingData = `
version: 1
learnings:
- id: learn-1
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: Some title
content: Some content
scope: project
tags:
- authentication
- security
useCount: 0
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingData);
const store = new LearningStore('project', '/test/project');
const results = store.search('authentication');
expect(results).toHaveLength(1);
});
});
describe('clear', () => {
it('should clear all learnings', () => {
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(`
version: 1
learnings:
- id: learn-1
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: Test
content: Content
scope: project
tags: []
useCount: 0
`);
const store = new LearningStore('project', '/test/project');
store.clear();
expect(store.count()).toBe(0);
});
});
describe('count', () => {
it('should return the number of learnings', () => {
const existingData = `
version: 1
learnings:
- id: learn-1
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: First
content: Content
scope: project
tags: []
useCount: 0
- id: learn-2
createdAt: "2024-01-10T09:00:00.000Z"
updatedAt: "2024-01-10T09:00:00.000Z"
source: session
title: Second
content: Content
scope: project
tags: []
useCount: 0
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingData);
const store = new LearningStore('project', '/test/project');
expect(store.count()).toBe(2);
});
});
});
@@ -0,0 +1,487 @@
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { MemoryIndexStore } from '../memory-index.js';
import type { Learning } from '../types.js';
vi.mock('node:fs', () => ({
existsSync: vi.fn(),
readFileSync: vi.fn(),
writeFileSync: vi.fn(),
mkdirSync: vi.fn(),
}));
describe('MemoryIndexStore', () => {
beforeEach(() => {
vi.clearAllMocks();
vi.useFakeTimers();
vi.setSystemTime(new Date('2024-01-15T10:00:00Z'));
});
afterEach(() => {
vi.useRealTimers();
vi.resetAllMocks();
});
const createMockLearning = (overrides: Partial<Learning> = {}): Learning => ({
id: 'learn-1',
createdAt: '2024-01-10T09:00:00.000Z',
updatedAt: '2024-01-10T09:00:00.000Z',
source: 'session',
title: 'React hooks best practices',
content: 'When using useEffect, always include cleanup functions for subscriptions.',
scope: 'project',
tags: ['react', 'hooks', 'best-practices'],
frameworks: ['react'],
useCount: 0,
...overrides,
});
describe('indexLearning', () => {
it('should index a learning by keywords and tags', () => {
vi.mocked(existsSync).mockReturnValue(false);
const store = new MemoryIndexStore('/test/project');
const learning = createMockLearning();
store.indexLearning(learning);
expect(vi.mocked(writeFileSync)).toHaveBeenCalled();
const [, content] = vi.mocked(writeFileSync).mock.calls[0];
// Should contain keyword entries
expect(content).toContain('react');
expect(content).toContain('hooks');
expect(content).toContain('useeffect');
expect(content).toContain('cleanup');
});
it('should add learning ID to existing keywords', () => {
const existingIndex = `
version: 1
lastUpdated: "2024-01-14T10:00:00.000Z"
entries:
react:
- existing-learn-1
tags:
react:
- existing-learn-1
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingIndex);
const store = new MemoryIndexStore('/test/project');
const learning = createMockLearning({ id: 'learn-2' });
store.indexLearning(learning);
const [, content] = vi.mocked(writeFileSync).mock.calls[0];
// Should have both IDs under react keyword
expect(content).toContain('existing-learn-1');
expect(content).toContain('learn-2');
});
it('should index frameworks as tags', () => {
vi.mocked(existsSync).mockReturnValue(false);
const store = new MemoryIndexStore('/test/project');
const learning = createMockLearning({
frameworks: ['nextjs', 'tailwind'],
});
store.indexLearning(learning);
const [, content] = vi.mocked(writeFileSync).mock.calls[0];
expect(content).toContain('nextjs');
expect(content).toContain('tailwind');
});
});
describe('removeLearning', () => {
it('should remove learning from all index entries', () => {
const existingIndex = `
version: 1
lastUpdated: "2024-01-14T10:00:00.000Z"
entries:
react:
- learn-1
- learn-2
hooks:
- learn-1
typescript:
- learn-2
tags:
react:
- learn-1
typescript:
- learn-2
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingIndex);
const store = new MemoryIndexStore('/test/project');
store.removeLearning('learn-1');
const [, content] = vi.mocked(writeFileSync).mock.calls[0];
// learn-1 should be removed
expect(content).not.toMatch(/learn-1/);
// learn-2 should still exist
expect(content).toContain('learn-2');
// hooks entry should be completely removed (was only learn-1)
expect(content).not.toContain('hooks:');
});
});
describe('searchByKeywords', () => {
it('should find learnings by keywords', () => {
const existingIndex = `
version: 1
lastUpdated: "2024-01-14T10:00:00.000Z"
entries:
react:
- learn-1
- learn-3
hooks:
- learn-1
typescript:
- learn-2
tags: {}
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingIndex);
const store = new MemoryIndexStore('/test/project');
const results = store.searchByKeywords('react hooks');
// learn-1 matches both 'react' and 'hooks', should be first
expect(results[0]).toBe('learn-1');
expect(results).toContain('learn-3');
});
it('should return empty array for no matches', () => {
const existingIndex = `
version: 1
lastUpdated: "2024-01-14T10:00:00.000Z"
entries:
react:
- learn-1
tags: {}
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingIndex);
const store = new MemoryIndexStore('/test/project');
const results = store.searchByKeywords('python django');
expect(results).toEqual([]);
});
it('should handle partial matches', () => {
const existingIndex = `
version: 1
lastUpdated: "2024-01-14T10:00:00.000Z"
entries:
authentication:
- learn-1
authorization:
- learn-2
tags: {}
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingIndex);
const store = new MemoryIndexStore('/test/project');
const results = store.searchByKeywords('auth');
expect(results).toContain('learn-1');
expect(results).toContain('learn-2');
});
});
describe('searchByTags', () => {
it('should find learnings by tags', () => {
const existingIndex = `
version: 1
lastUpdated: "2024-01-14T10:00:00.000Z"
entries: {}
tags:
react:
- learn-1
- learn-2
nextjs:
- learn-1
express:
- learn-3
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingIndex);
const store = new MemoryIndexStore('/test/project');
const results = store.searchByTags(['react', 'nextjs']);
// learn-1 matches both tags, should be first
expect(results[0]).toBe('learn-1');
expect(results).toContain('learn-2');
expect(results).not.toContain('learn-3');
});
it('should be case-insensitive', () => {
const existingIndex = `
version: 1
lastUpdated: "2024-01-14T10:00:00.000Z"
entries: {}
tags:
react:
- learn-1
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingIndex);
const store = new MemoryIndexStore('/test/project');
const results = store.searchByTags(['REACT']);
expect(results).toContain('learn-1');
});
});
describe('search', () => {
it('should combine keyword and tag search', () => {
const existingIndex = `
version: 1
lastUpdated: "2024-01-14T10:00:00.000Z"
entries:
hooks:
- learn-1
- learn-2
state:
- learn-3
tags:
react:
- learn-1
- learn-3
vue:
- learn-2
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingIndex);
const store = new MemoryIndexStore('/test/project');
const results = store.search('hooks', ['react']);
// learn-1 matches both keyword and tag
expect(results[0]).toBe('learn-1');
});
it('should handle keyword-only search', () => {
const existingIndex = `
version: 1
lastUpdated: "2024-01-14T10:00:00.000Z"
entries:
hooks:
- learn-1
tags: {}
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingIndex);
const store = new MemoryIndexStore('/test/project');
const results = store.search('hooks');
expect(results).toContain('learn-1');
});
it('should handle tag-only search', () => {
const existingIndex = `
version: 1
lastUpdated: "2024-01-14T10:00:00.000Z"
entries: {}
tags:
react:
- learn-1
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingIndex);
const store = new MemoryIndexStore('/test/project');
const results = store.search('', ['react']);
expect(results).toContain('learn-1');
});
});
describe('getAllTags', () => {
it('should return all unique tags sorted', () => {
const existingIndex = `
version: 1
lastUpdated: "2024-01-14T10:00:00.000Z"
entries: {}
tags:
react:
- learn-1
typescript:
- learn-2
nextjs:
- learn-1
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingIndex);
const store = new MemoryIndexStore('/test/project');
const tags = store.getAllTags();
expect(tags).toEqual(['nextjs', 'react', 'typescript']);
});
});
describe('getTagCounts', () => {
it('should return tag usage counts', () => {
const existingIndex = `
version: 1
lastUpdated: "2024-01-14T10:00:00.000Z"
entries: {}
tags:
react:
- learn-1
- learn-2
- learn-3
typescript:
- learn-1
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingIndex);
const store = new MemoryIndexStore('/test/project');
const counts = store.getTagCounts();
expect(counts).toEqual({
react: 3,
typescript: 1,
});
});
});
describe('rebuildIndex', () => {
it('should rebuild index from learnings', () => {
vi.mocked(existsSync).mockReturnValue(false);
const store = new MemoryIndexStore('/test/project');
const learnings: Learning[] = [
{
id: 'learn-1',
createdAt: '2024-01-10T09:00:00.000Z',
updatedAt: '2024-01-10T09:00:00.000Z',
source: 'session',
title: 'React patterns',
content: 'Using React hooks effectively',
scope: 'project',
tags: ['react'],
useCount: 0,
},
{
id: 'learn-2',
createdAt: '2024-01-10T09:00:00.000Z',
updatedAt: '2024-01-10T09:00:00.000Z',
source: 'session',
title: 'TypeScript tips',
content: 'TypeScript generics explained',
scope: 'project',
tags: ['typescript'],
useCount: 0,
},
];
store.rebuildIndex(learnings);
// Get the last write call (after both learnings are indexed)
const calls = vi.mocked(writeFileSync).mock.calls;
const [, content] = calls[calls.length - 1];
expect(content).toContain('react');
expect(content).toContain('typescript');
expect(content).toContain('learn-1');
expect(content).toContain('learn-2');
});
});
describe('clear', () => {
it('should clear the index', () => {
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(`
version: 1
lastUpdated: "2024-01-14T10:00:00.000Z"
entries:
react:
- learn-1
tags:
react:
- learn-1
`);
const store = new MemoryIndexStore('/test/project');
store.clear();
const [, content] = vi.mocked(writeFileSync).mock.calls[0];
expect(content).toContain('entries: {}');
expect(content).toContain('tags: {}');
});
});
describe('getStats', () => {
it('should return index statistics', () => {
const existingIndex = `
version: 1
lastUpdated: "2024-01-14T10:00:00.000Z"
entries:
react:
- learn-1
hooks:
- learn-1
typescript:
- learn-2
tags:
react:
- learn-1
typescript:
- learn-2
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingIndex);
const store = new MemoryIndexStore('/test/project');
const stats = store.getStats();
expect(stats.keywords).toBe(3);
expect(stats.tags).toBe(2);
expect(stats.lastUpdated).toBe('2024-01-14T10:00:00.000Z');
});
});
describe('exists', () => {
it('should return true when file exists', () => {
vi.mocked(existsSync).mockReturnValue(true);
const store = new MemoryIndexStore('/test/project');
expect(store.exists()).toBe(true);
});
it('should return false when file does not exist', () => {
vi.mocked(existsSync).mockReturnValue(false);
const store = new MemoryIndexStore('/test/project');
expect(store.exists()).toBe(false);
});
});
});
@@ -0,0 +1,444 @@
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { ObservationStore } from '../observation-store.js';
import type { ObservationType, ObservationContent } from '../types.js';
vi.mock('node:fs', () => ({
existsSync: vi.fn(),
readFileSync: vi.fn(),
writeFileSync: vi.fn(),
mkdirSync: vi.fn(),
}));
// Helper to check if a string is a valid UUID
const isValidUUID = (str: string): boolean => {
const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
return uuidRegex.test(str);
};
describe('ObservationStore', () => {
beforeEach(() => {
vi.clearAllMocks();
vi.useFakeTimers();
vi.setSystemTime(new Date('2024-01-15T10:00:00Z'));
});
afterEach(() => {
vi.useRealTimers();
vi.resetAllMocks();
});
describe('constructor', () => {
it('should set the correct file path', () => {
vi.mocked(existsSync).mockReturnValue(false);
const store = new ObservationStore('/test/project');
expect(store).toBeDefined();
});
it('should accept a custom session ID', () => {
vi.mocked(existsSync).mockReturnValue(false);
const store = new ObservationStore('/test/project', 'custom-session-id');
expect(store.getSessionId()).toBe('custom-session-id');
});
it('should generate a session ID if not provided', () => {
vi.mocked(existsSync).mockReturnValue(false);
const store = new ObservationStore('/test/project');
expect(isValidUUID(store.getSessionId())).toBe(true);
});
});
describe('add', () => {
it('should add a new observation', () => {
vi.mocked(existsSync).mockReturnValue(false);
const store = new ObservationStore('/test/project', 'session-1');
const content: ObservationContent = {
action: 'Created new file',
context: 'User requested new component',
result: 'File created successfully',
files: ['src/Component.tsx'],
tags: ['react', 'typescript'],
};
const observation = store.add('file_change', content, 'claude-code', 75);
expect(isValidUUID(observation.id)).toBe(true);
expect(observation).toMatchObject({
timestamp: '2024-01-15T10:00:00.000Z',
sessionId: 'session-1',
agent: 'claude-code',
type: 'file_change',
content,
relevance: 75,
});
expect(vi.mocked(writeFileSync)).toHaveBeenCalled();
});
it('should use default relevance of 50', () => {
vi.mocked(existsSync).mockReturnValue(false);
const store = new ObservationStore('/test/project');
const observation = store.add(
'decision',
{ action: 'test', context: 'test' },
'cursor'
);
expect(observation.relevance).toBe(50);
});
});
describe('getAll', () => {
it('should return all observations', () => {
const existingData = `
version: 1
sessionId: session-1
observations:
- id: obs-1
timestamp: "2024-01-15T09:00:00.000Z"
sessionId: session-1
agent: claude-code
type: tool_use
content:
action: Read file
context: Analyzing code
relevance: 60
- id: obs-2
timestamp: "2024-01-15T09:30:00.000Z"
sessionId: session-1
agent: claude-code
type: decision
content:
action: Use React hooks
context: State management
relevance: 80
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingData);
const store = new ObservationStore('/test/project', 'session-1');
const observations = store.getAll();
expect(observations).toHaveLength(2);
expect(observations[0].id).toBe('obs-1');
expect(observations[1].id).toBe('obs-2');
});
it('should return empty array when no observations exist', () => {
vi.mocked(existsSync).mockReturnValue(false);
const store = new ObservationStore('/test/project');
const observations = store.getAll();
expect(observations).toEqual([]);
});
});
describe('getByType', () => {
it('should filter observations by type', () => {
const existingData = `
version: 1
sessionId: session-1
observations:
- id: obs-1
timestamp: "2024-01-15T09:00:00.000Z"
sessionId: session-1
agent: claude-code
type: error
content:
action: Build failed
context: TypeScript error
error: Type mismatch
relevance: 90
- id: obs-2
timestamp: "2024-01-15T09:30:00.000Z"
sessionId: session-1
agent: claude-code
type: solution
content:
action: Fixed error
context: Added type annotation
solution: Added explicit type
relevance: 85
- id: obs-3
timestamp: "2024-01-15T10:00:00.000Z"
sessionId: session-1
agent: claude-code
type: error
content:
action: Test failed
context: Unit test
error: Assertion failed
relevance: 70
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingData);
const store = new ObservationStore('/test/project', 'session-1');
const errors = store.getByType('error');
expect(errors).toHaveLength(2);
expect(errors[0].type).toBe('error');
expect(errors[1].type).toBe('error');
});
});
describe('getByRelevance', () => {
it('should filter observations by minimum relevance', () => {
const existingData = `
version: 1
sessionId: session-1
observations:
- id: obs-1
timestamp: "2024-01-15T09:00:00.000Z"
sessionId: session-1
agent: claude-code
type: decision
content:
action: Test
context: Test
relevance: 30
- id: obs-2
timestamp: "2024-01-15T09:30:00.000Z"
sessionId: session-1
agent: claude-code
type: decision
content:
action: Test
context: Test
relevance: 70
- id: obs-3
timestamp: "2024-01-15T10:00:00.000Z"
sessionId: session-1
agent: claude-code
type: decision
content:
action: Test
context: Test
relevance: 90
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingData);
const store = new ObservationStore('/test/project', 'session-1');
const highRelevance = store.getByRelevance(60);
expect(highRelevance).toHaveLength(2);
expect(highRelevance[0].relevance).toBe(70);
expect(highRelevance[1].relevance).toBe(90);
});
});
describe('getRecent', () => {
it('should return the most recent observations', () => {
const existingData = `
version: 1
sessionId: session-1
observations:
- id: obs-1
timestamp: "2024-01-15T09:00:00.000Z"
sessionId: session-1
agent: claude-code
type: decision
content:
action: First
context: Test
relevance: 50
- id: obs-2
timestamp: "2024-01-15T09:30:00.000Z"
sessionId: session-1
agent: claude-code
type: decision
content:
action: Second
context: Test
relevance: 50
- id: obs-3
timestamp: "2024-01-15T10:00:00.000Z"
sessionId: session-1
agent: claude-code
type: decision
content:
action: Third
context: Test
relevance: 50
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingData);
const store = new ObservationStore('/test/project', 'session-1');
const recent = store.getRecent(2);
expect(recent).toHaveLength(2);
expect(recent[0].content.action).toBe('Second');
expect(recent[1].content.action).toBe('Third');
});
});
describe('getUncompressed', () => {
it('should return observations not in the compressed list', () => {
const existingData = `
version: 1
sessionId: session-1
observations:
- id: obs-1
timestamp: "2024-01-15T09:00:00.000Z"
sessionId: session-1
agent: claude-code
type: decision
content:
action: Test
context: Test
relevance: 50
- id: obs-2
timestamp: "2024-01-15T09:30:00.000Z"
sessionId: session-1
agent: claude-code
type: decision
content:
action: Test
context: Test
relevance: 50
- id: obs-3
timestamp: "2024-01-15T10:00:00.000Z"
sessionId: session-1
agent: claude-code
type: decision
content:
action: Test
context: Test
relevance: 50
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingData);
const store = new ObservationStore('/test/project', 'session-1');
const uncompressed = store.getUncompressed(['obs-1', 'obs-3']);
expect(uncompressed).toHaveLength(1);
expect(uncompressed[0].id).toBe('obs-2');
});
});
describe('clear', () => {
it('should clear all observations', () => {
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(`
version: 1
sessionId: session-1
observations:
- id: obs-1
timestamp: "2024-01-15T09:00:00.000Z"
sessionId: session-1
agent: claude-code
type: decision
content:
action: Test
context: Test
relevance: 50
`);
const store = new ObservationStore('/test/project', 'session-1');
store.clear();
const [, content] = vi.mocked(writeFileSync).mock.calls[0];
expect(content).toContain('observations: []');
});
});
describe('session management', () => {
it('should clear observations when session ID changes', () => {
const existingData = `
version: 1
sessionId: old-session
observations:
- id: obs-1
timestamp: "2024-01-15T09:00:00.000Z"
sessionId: old-session
agent: claude-code
type: decision
content:
action: Test
context: Test
relevance: 50
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingData);
const store = new ObservationStore('/test/project', 'new-session');
const observations = store.getAll();
expect(observations).toHaveLength(0);
});
it('should allow setting session ID', () => {
vi.mocked(existsSync).mockReturnValue(false);
const store = new ObservationStore('/test/project', 'initial-session');
store.setSessionId('updated-session');
expect(store.getSessionId()).toBe('updated-session');
});
});
describe('exists', () => {
it('should return true when file exists', () => {
vi.mocked(existsSync).mockReturnValue(true);
const store = new ObservationStore('/test/project');
expect(store.exists()).toBe(true);
});
it('should return false when file does not exist', () => {
vi.mocked(existsSync).mockReturnValue(false);
const store = new ObservationStore('/test/project');
expect(store.exists()).toBe(false);
});
});
describe('count', () => {
it('should return the number of observations', () => {
const existingData = `
version: 1
sessionId: session-1
observations:
- id: obs-1
timestamp: "2024-01-15T09:00:00.000Z"
sessionId: session-1
agent: claude-code
type: decision
content:
action: Test
context: Test
relevance: 50
- id: obs-2
timestamp: "2024-01-15T09:30:00.000Z"
sessionId: session-1
agent: claude-code
type: decision
content:
action: Test
context: Test
relevance: 50
`;
vi.mocked(existsSync).mockReturnValue(true);
vi.mocked(readFileSync).mockReturnValue(existingData);
const store = new ObservationStore('/test/project', 'session-1');
expect(store.count()).toBe(2);
});
});
});
@@ -0,0 +1,421 @@
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { MemoryObserver, createMemoryObserver, type ObservableEvent } from '../observer.js';
import type { ExecutionProgressEvent } from '../../executor/engine.js';
vi.mock('node:fs', () => ({
existsSync: vi.fn(),
readFileSync: vi.fn(),
writeFileSync: vi.fn(),
mkdirSync: vi.fn(),
}));
describe('MemoryObserver', () => {
beforeEach(() => {
vi.clearAllMocks();
vi.mocked(existsSync).mockReturnValue(false);
});
afterEach(() => {
vi.resetAllMocks();
});
describe('constructor', () => {
it('should create an observer with default config', () => {
const observer = new MemoryObserver('/test/project');
expect(observer).toBeDefined();
expect(observer.getObservationCount()).toBe(0);
});
it('should accept custom session ID', () => {
const observer = new MemoryObserver('/test/project', 'custom-session');
expect(observer.getSessionId()).toBe('custom-session');
});
it('should accept custom config', () => {
const observer = new MemoryObserver('/test/project', undefined, {
minRelevance: 50,
captureTaskStarts: true,
});
expect(observer).toBeDefined();
});
});
describe('setAgent', () => {
it('should set the current agent', () => {
const observer = new MemoryObserver('/test/project');
observer.setAgent('cursor');
// Agent is used when creating observations
expect(observer).toBeDefined();
});
});
describe('setSkillName', () => {
it('should set the current skill name', () => {
const observer = new MemoryObserver('/test/project');
observer.setSkillName('test-skill');
expect(observer).toBeDefined();
});
});
describe('observe', () => {
it('should capture high-relevance events', () => {
const observer = new MemoryObserver('/test/project');
const event: ObservableEvent = {
type: 'error_encountered',
timestamp: new Date().toISOString(),
error: 'TypeError: Cannot read property of undefined',
context: 'Running test suite',
};
const observation = observer.observe(event);
expect(observation).not.toBeNull();
expect(observation?.type).toBe('error');
expect(observation?.relevance).toBeGreaterThanOrEqual(80);
});
it('should filter low-relevance events by default', () => {
const observer = new MemoryObserver('/test/project', undefined, {
minRelevance: 50,
});
const event: ObservableEvent = {
type: 'task_start',
timestamp: new Date().toISOString(),
taskName: 'Test task',
};
// Task starts have low relevance and are disabled by default
const observation = observer.observe(event);
expect(observation).toBeNull();
});
it('should capture task starts when enabled', () => {
const observer = new MemoryObserver('/test/project', undefined, {
captureTaskStarts: true,
minRelevance: 0,
});
const event: ObservableEvent = {
type: 'task_start',
timestamp: new Date().toISOString(),
taskName: 'Test task',
};
const observation = observer.observe(event);
expect(observation).not.toBeNull();
});
it('should capture solutions with high relevance', () => {
const observer = new MemoryObserver('/test/project');
const event: ObservableEvent = {
type: 'solution_applied',
timestamp: new Date().toISOString(),
output: 'Added null check before accessing property',
context: 'Fixed TypeError',
};
const observation = observer.observe(event);
expect(observation).not.toBeNull();
expect(observation?.type).toBe('solution');
expect(observation?.relevance).toBeGreaterThanOrEqual(85);
});
it('should capture decisions', () => {
const observer = new MemoryObserver('/test/project');
const event: ObservableEvent = {
type: 'checkpoint_decision',
timestamp: new Date().toISOString(),
decision: 'Use React hooks',
context: 'Choosing state management approach',
};
const observation = observer.observe(event);
expect(observation).not.toBeNull();
expect(observation?.type).toBe('decision');
});
it('should capture file modifications', () => {
const observer = new MemoryObserver('/test/project');
const event: ObservableEvent = {
type: 'file_modified',
timestamp: new Date().toISOString(),
files: ['src/App.tsx', 'src/index.ts'],
context: 'Refactoring components',
};
const observation = observer.observe(event);
expect(observation).not.toBeNull();
expect(observation?.type).toBe('file_change');
expect(observation?.content.files).toContain('src/App.tsx');
});
});
describe('createProgressCallback', () => {
it('should create a callback that captures progress events', () => {
const observer = new MemoryObserver('/test/project', undefined, {
minRelevance: 0,
});
const callback = observer.createProgressCallback();
const progressEvent: ExecutionProgressEvent = {
type: 'task_complete',
taskId: 'task-1',
taskName: 'Build project',
taskIndex: 0,
totalTasks: 3,
status: 'completed',
message: 'Build completed successfully',
};
callback(progressEvent);
expect(observer.getObservationCount()).toBeGreaterThanOrEqual(0);
});
it('should capture failed task events', () => {
const observer = new MemoryObserver('/test/project');
const callback = observer.createProgressCallback();
const progressEvent: ExecutionProgressEvent = {
type: 'task_complete',
taskId: 'task-1',
taskName: 'Run tests',
status: 'failed',
error: 'Test suite failed: 3 tests failed',
};
callback(progressEvent);
const observations = observer.getObservations();
const errorObs = observations.find((o) => o.type === 'error');
expect(errorObs).toBeDefined();
});
});
describe('recordFileModification', () => {
it('should record file modifications', () => {
const observer = new MemoryObserver('/test/project');
const observation = observer.recordFileModification(
['src/components/Button.tsx'],
'Updated button styling'
);
expect(observation).not.toBeNull();
expect(observation?.type).toBe('file_change');
expect(observation?.content.files).toContain('src/components/Button.tsx');
});
});
describe('recordError', () => {
it('should record errors', () => {
const observer = new MemoryObserver('/test/project');
const observation = observer.recordError(
'ModuleNotFoundError: Cannot find module react',
'Import resolution'
);
expect(observation).not.toBeNull();
expect(observation?.type).toBe('error');
expect(observation?.content.error).toContain('ModuleNotFoundError');
});
});
describe('recordSolution', () => {
it('should record solutions', () => {
const observer = new MemoryObserver('/test/project');
const observation = observer.recordSolution(
'Installed missing dependency: npm install react',
'Fixed import error',
'ModuleNotFoundError'
);
expect(observation).not.toBeNull();
expect(observation?.type).toBe('solution');
});
it('should boost relevance for solutions matching pending errors', () => {
const observer = new MemoryObserver('/test/project');
// First record an error
observer.recordError('TypeError: x is not a function', 'Runtime error');
// Then record a matching solution
const solution = observer.recordSolution(
'Changed x to be a function',
'Fixed type error',
'TypeError: x is not a function'
);
expect(solution).not.toBeNull();
expect(solution?.relevance).toBeGreaterThanOrEqual(90);
});
});
describe('recordDecision', () => {
it('should record decisions with options', () => {
const observer = new MemoryObserver('/test/project');
const observation = observer.recordDecision(
'Use TypeScript',
['TypeScript', 'JavaScript', 'Flow'],
'Language selection'
);
expect(observation).not.toBeNull();
expect(observation?.type).toBe('decision');
expect(observation?.content.context).toContain('TypeScript');
expect(observation?.content.context).toContain('JavaScript');
});
});
describe('recordExecutionStart', () => {
it('should record execution start', () => {
const observer = new MemoryObserver('/test/project', undefined, {
minRelevance: 0,
});
const observation = observer.recordExecutionStart('code-review', 'claude-code');
expect(observation).not.toBeNull();
expect(observation?.content.action).toContain('code-review');
});
});
describe('recordExecutionPause', () => {
it('should record execution pause', () => {
const observer = new MemoryObserver('/test/project');
const observation = observer.recordExecutionPause('User requested pause');
expect(observation).not.toBeNull();
expect(observation?.type).toBe('checkpoint');
});
});
describe('tag generation', () => {
it('should generate typescript tags for .ts files', () => {
const observer = new MemoryObserver('/test/project');
const observation = observer.recordFileModification(
['src/utils.ts', 'src/types.ts'],
'Updated utilities'
);
expect(observation?.content.tags).toContain('typescript');
});
it('should generate testing tags for test files', () => {
const observer = new MemoryObserver('/test/project');
const observation = observer.recordFileModification(
['src/__tests__/utils.test.ts'],
'Added tests'
);
expect(observation?.content.tags).toContain('testing');
});
it('should generate error-related tags from error content', () => {
const observer = new MemoryObserver('/test/project');
const observation = observer.recordError(
'TypeError: Cannot read property of null',
'Runtime error'
);
expect(observation?.content.tags).toContain('null-check');
});
});
describe('relevance scoring', () => {
it('should score errors higher than task completions', () => {
const observer = new MemoryObserver('/test/project', undefined, {
minRelevance: 0,
captureTaskStarts: true,
});
const errorObs = observer.observe({
type: 'error_encountered',
timestamp: new Date().toISOString(),
error: 'Test error',
context: 'Test',
});
const taskObs = observer.observe({
type: 'task_complete',
timestamp: new Date().toISOString(),
taskName: 'Test task',
context: 'Test',
});
expect(errorObs?.relevance).toBeGreaterThan(taskObs?.relevance || 0);
});
it('should use custom relevance scorer when provided', () => {
const customScorer = vi.fn().mockReturnValue(75);
const observer = new MemoryObserver('/test/project', undefined, {
relevanceScorer: customScorer,
minRelevance: 0,
});
observer.observe({
type: 'task_complete',
timestamp: new Date().toISOString(),
taskName: 'Test',
context: 'Test',
});
expect(customScorer).toHaveBeenCalled();
});
});
describe('clear', () => {
it('should clear all observations', () => {
const observer = new MemoryObserver('/test/project');
observer.recordError('Test error', 'Test context');
expect(observer.getObservationCount()).toBeGreaterThan(0);
observer.clear();
expect(observer.getObservationCount()).toBe(0);
});
});
describe('getObservations', () => {
it('should return all observations', () => {
const observer = new MemoryObserver('/test/project');
observer.recordError('Error 1', 'Context 1');
observer.recordError('Error 2', 'Context 2');
const observations = observer.getObservations();
expect(observations.length).toBe(2);
});
});
describe('createMemoryObserver', () => {
it('should create an observer instance', () => {
const observer = createMemoryObserver('/test/project');
expect(observer).toBeInstanceOf(MemoryObserver);
});
it('should pass through options', () => {
const observer = createMemoryObserver('/test/project', 'session-123', {
minRelevance: 60,
});
expect(observer.getSessionId()).toBe('session-123');
});
});
});
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,235 @@
/**
* Memory-Enabled Execution Engine Integration
*
* Provides utilities to integrate MemoryObserver with SkillExecutionEngine.
*/
import type { AgentType } from '../types.js';
import {
SkillExecutionEngine,
createExecutionEngine,
type ExecutionProgressCallback,
type ExecutionProgressEvent,
} from '../executor/engine.js';
import type { CheckpointHandler, ExecutionOptions, ExecutableSkill } from '../executor/types.js';
import { MemoryObserver, type MemoryObserverConfig } from './observer.js';
/**
* Options for creating a memory-enabled execution engine
*/
export interface MemoryEnabledEngineOptions {
/** Checkpoint handler for interactive checkpoints */
checkpointHandler?: CheckpointHandler;
/** Additional progress callback (called alongside memory observer) */
onProgress?: ExecutionProgressCallback;
/** Memory observer configuration */
memoryConfig?: MemoryObserverConfig;
/** Session ID for the memory observer */
sessionId?: string;
/** Default agent type */
defaultAgent?: AgentType;
}
/**
* Memory-enabled execution engine wrapper
*/
export class MemoryEnabledEngine {
private engine: SkillExecutionEngine;
private observer: MemoryObserver;
private userProgressCallback?: ExecutionProgressCallback;
constructor(projectPath: string, options: MemoryEnabledEngineOptions = {}) {
// Create memory observer
this.observer = new MemoryObserver(projectPath, options.sessionId, options.memoryConfig);
// Set default agent if provided
if (options.defaultAgent) {
this.observer.setAgent(options.defaultAgent);
}
// Store user's progress callback
this.userProgressCallback = options.onProgress;
// Create the combined progress callback
const combinedProgressCallback: ExecutionProgressCallback = (event: ExecutionProgressEvent) => {
// Forward to memory observer
const observerCallback = this.observer.createProgressCallback();
observerCallback(event);
// Forward to user's callback if provided
if (this.userProgressCallback) {
this.userProgressCallback(event);
}
};
// Create the underlying engine with the combined callback
this.engine = createExecutionEngine(projectPath, {
checkpointHandler: options.checkpointHandler,
onProgress: combinedProgressCallback,
});
}
/**
* Execute a skill with memory observation
*/
async execute(
skill: ExecutableSkill,
options: ExecutionOptions = {}
): ReturnType<SkillExecutionEngine['execute']> {
// Set skill name in observer
this.observer.setSkillName(skill.name);
// Set agent if provided in options
if (options.agent) {
this.observer.setAgent(options.agent);
}
// Record execution start
this.observer.recordExecutionStart(skill.name, options.agent || 'claude-code');
try {
// Execute the skill
const result = await this.engine.execute(skill, options);
// Record file modifications from result
if (result.filesModified.length > 0) {
this.observer.recordFileModification(
result.filesModified,
`Files modified during skill "${skill.name}" execution`
);
}
// Record any errors
if (result.error) {
this.observer.recordError(result.error, `Skill "${skill.name}" failed`);
}
return result;
} catch (error) {
// Record unexpected errors
const errorMessage = error instanceof Error ? error.message : String(error);
this.observer.recordError(errorMessage, `Unexpected error during skill "${skill.name}" execution`);
throw error;
}
}
/**
* Record a manual error observation
*/
recordError(error: string, context: string, taskId?: string): void {
this.observer.recordError(error, context, taskId);
}
/**
* Record a manual solution observation
*/
recordSolution(solution: string, context: string, relatedError?: string): void {
this.observer.recordSolution(solution, context, relatedError);
}
/**
* Record a file modification observation
*/
recordFileModification(files: string[], context: string): void {
this.observer.recordFileModification(files, context);
}
/**
* Record a decision observation
*/
recordDecision(decision: string, options: string[], context: string): void {
this.observer.recordDecision(decision, options, context);
}
/**
* Pause execution
*/
pause(): boolean {
const paused = this.engine.pause();
if (paused) {
this.observer.recordExecutionPause();
}
return paused;
}
/**
* Check if execution is paused
*/
isPaused(): boolean {
return this.engine.isPaused();
}
/**
* Get the memory observer
*/
getObserver(): MemoryObserver {
return this.observer;
}
/**
* Get the underlying execution engine
*/
getEngine(): SkillExecutionEngine {
return this.engine;
}
/**
* Get the session manager
*/
getSessionManager(): ReturnType<SkillExecutionEngine['getSessionManager']> {
return this.engine.getSessionManager();
}
/**
* Get observation count
*/
getObservationCount(): number {
return this.observer.getObservationCount();
}
/**
* Get all observations
*/
getObservations(): ReturnType<MemoryObserver['getObservations']> {
return this.observer.getObservations();
}
/**
* Clear observations
*/
clearObservations(): void {
this.observer.clear();
}
}
/**
* Create a memory-enabled execution engine
*/
export function createMemoryEnabledEngine(
projectPath: string,
options?: MemoryEnabledEngineOptions
): MemoryEnabledEngine {
return new MemoryEnabledEngine(projectPath, options);
}
/**
* Wrap an existing progress callback with memory observation
*/
export function wrapProgressCallbackWithMemory(
projectPath: string,
existingCallback?: ExecutionProgressCallback,
memoryConfig?: MemoryObserverConfig,
sessionId?: string
): { callback: ExecutionProgressCallback; observer: MemoryObserver } {
const observer = new MemoryObserver(projectPath, sessionId, memoryConfig);
const observerCallback = observer.createProgressCallback();
const wrappedCallback: ExecutionProgressCallback = (event: ExecutionProgressEvent) => {
observerCallback(event);
if (existingCallback) {
existingCallback(event);
}
};
return { callback: wrappedCallback, observer };
}
+50
View File
@@ -0,0 +1,50 @@
// Memory Module - Cross-Agent Session Memory System
// Provides persistent memory across all AI coding agents
export * from './types.js';
export { ObservationStore } from './observation-store.js';
export { LearningStore } from './learning-store.js';
export { MemoryIndexStore } from './memory-index.js';
export {
getMemoryPaths,
initializeMemoryDirectory,
memoryDirectoryExists,
globalMemoryDirectoryExists,
getMemoryStatus,
type MemoryPaths,
type MemoryStatus,
} from './initializer.js';
export {
MemoryObserver,
createMemoryObserver,
type ObservableEvent,
type ObservableEventType,
type MemoryObserverConfig,
} from './observer.js';
export {
MemoryEnabledEngine,
createMemoryEnabledEngine,
wrapProgressCallbackWithMemory,
type MemoryEnabledEngineOptions,
} from './engine-integration.js';
export {
RuleBasedCompressor,
APIBasedCompressor,
MemoryCompressor,
LearningConsolidator,
createRuleBasedCompressor,
createAPIBasedCompressor,
createMemoryCompressor,
type CompressionEngine,
type CompressedLearning,
type CompressionResult,
type CompressionOptions,
type APICompressionConfig,
} from './compressor.js';
export {
MemoryInjector,
createMemoryInjector,
type InjectionOptions,
type InjectedMemory,
type InjectionResult,
} from './injector.js';
+78
View File
@@ -0,0 +1,78 @@
import { existsSync, mkdirSync } from 'node:fs';
import { join } from 'node:path';
import { homedir } from 'node:os';
export interface MemoryPaths {
projectMemoryDir: string;
globalMemoryDir: string;
observationsFile: string;
learningsFile: string;
indexFile: string;
globalLearningsFile: string;
globalIndexFile: string;
}
export function getMemoryPaths(projectPath: string): MemoryPaths {
const projectMemoryDir = join(projectPath, '.skillkit', 'memory');
const globalMemoryDir = join(homedir(), '.skillkit', 'memory');
return {
projectMemoryDir,
globalMemoryDir,
observationsFile: join(projectMemoryDir, 'observations.yaml'),
learningsFile: join(projectMemoryDir, 'learnings.yaml'),
indexFile: join(projectMemoryDir, 'index.yaml'),
globalLearningsFile: join(globalMemoryDir, 'global.yaml'),
globalIndexFile: join(globalMemoryDir, 'index.yaml'),
};
}
export function initializeMemoryDirectory(projectPath: string): MemoryPaths {
const paths = getMemoryPaths(projectPath);
// Create project memory directory
if (!existsSync(paths.projectMemoryDir)) {
mkdirSync(paths.projectMemoryDir, { recursive: true });
}
// Create global memory directory
if (!existsSync(paths.globalMemoryDir)) {
mkdirSync(paths.globalMemoryDir, { recursive: true });
}
return paths;
}
export function memoryDirectoryExists(projectPath: string): boolean {
const paths = getMemoryPaths(projectPath);
return existsSync(paths.projectMemoryDir);
}
export function globalMemoryDirectoryExists(): boolean {
const globalMemoryDir = join(homedir(), '.skillkit', 'memory');
return existsSync(globalMemoryDir);
}
export interface MemoryStatus {
projectMemoryExists: boolean;
globalMemoryExists: boolean;
hasObservations: boolean;
hasLearnings: boolean;
hasGlobalLearnings: boolean;
hasIndex: boolean;
hasGlobalIndex: boolean;
}
export function getMemoryStatus(projectPath: string): MemoryStatus {
const paths = getMemoryPaths(projectPath);
return {
projectMemoryExists: existsSync(paths.projectMemoryDir),
globalMemoryExists: existsSync(paths.globalMemoryDir),
hasObservations: existsSync(paths.observationsFile),
hasLearnings: existsSync(paths.learningsFile),
hasGlobalLearnings: existsSync(paths.globalLearningsFile),
hasIndex: existsSync(paths.indexFile),
hasGlobalIndex: existsSync(paths.globalIndexFile),
};
}
+716
View File
@@ -0,0 +1,716 @@
/**
* Memory Injector
*
* Injects relevant memories into agent context with relevance matching,
* agent-specific formatting, and token budgeting.
*/
import type { AgentType } from '../types.js';
import type { ProjectContext } from '../context/types.js';
import type { Learning, MemorySummary, MemoryPreview, MemoryFull } from './types.js';
import { LearningStore } from './learning-store.js';
/**
* Injection options
*/
export interface InjectionOptions {
/** Maximum tokens to use for injected memories */
maxTokens?: number;
/** Minimum relevance score to include (0-100) */
minRelevance?: number;
/** Maximum number of learnings to inject */
maxLearnings?: number;
/** Include global memories */
includeGlobal?: boolean;
/** Specific tags to match */
tags?: string[];
/** Current task description for relevance matching */
currentTask?: string;
/** Progressive disclosure level */
disclosureLevel?: 'summary' | 'preview' | 'full';
}
/**
* Injected memory with relevance score
*/
export interface InjectedMemory {
learning: Learning;
relevanceScore: number;
matchedBy: {
frameworks: string[];
tags: string[];
keywords: string[];
patterns: string[];
};
tokenEstimate: number;
}
/**
* Injection result
*/
export interface InjectionResult {
memories: InjectedMemory[];
formattedContent: string;
totalTokens: number;
stats: {
considered: number;
matched: number;
injected: number;
truncated: number;
};
}
/**
* Default injection options
*/
const DEFAULT_OPTIONS: Required<Omit<InjectionOptions, 'tags' | 'currentTask'>> = {
maxTokens: 2000,
minRelevance: 30,
maxLearnings: 10,
includeGlobal: true,
disclosureLevel: 'preview',
};
/**
* Approximate tokens per character (conservative estimate)
*/
const TOKENS_PER_CHAR = 0.25;
/**
* Memory Injector
*
* Retrieves and formats relevant memories for injection into agent context.
*/
export class MemoryInjector {
private projectStore: LearningStore;
private globalStore: LearningStore;
private projectContext?: ProjectContext;
constructor(
projectPath: string,
projectName?: string,
projectContext?: ProjectContext
) {
this.projectStore = new LearningStore('project', projectPath, projectName);
this.globalStore = new LearningStore('global');
this.projectContext = projectContext;
}
/**
* Set project context for better relevance matching
*/
setProjectContext(context: ProjectContext): void {
this.projectContext = context;
}
/**
* Get relevant memories for injection
*/
async getRelevantMemories(options: InjectionOptions = {}): Promise<InjectedMemory[]> {
const opts = { ...DEFAULT_OPTIONS, ...options };
// Collect all learnings
const projectLearnings = this.projectStore.getAll();
const globalLearnings = opts.includeGlobal ? this.globalStore.getAll() : [];
const allLearnings = [...projectLearnings, ...globalLearnings];
// Score each learning for relevance
const scored = allLearnings.map((learning) => ({
learning,
...this.scoreLearning(learning, opts),
}));
// Filter by minimum relevance
const filtered = scored.filter((s) => s.relevanceScore >= opts.minRelevance);
// Sort by relevance (descending)
filtered.sort((a, b) => b.relevanceScore - a.relevanceScore);
// Limit to max learnings
return filtered.slice(0, opts.maxLearnings);
}
/**
* Score a learning for relevance to current context
*/
private scoreLearning(
learning: Learning,
options: InjectionOptions
): Omit<InjectedMemory, 'learning'> {
let score = 0;
const matchedBy = {
frameworks: [] as string[],
tags: [] as string[],
keywords: [] as string[],
patterns: [] as string[],
};
// Match by frameworks from project context
if (this.projectContext?.stack) {
const projectFrameworks = this.extractFrameworkNames();
const learningFrameworks = learning.frameworks || [];
for (const fw of learningFrameworks) {
if (projectFrameworks.has(fw.toLowerCase())) {
score += 15;
matchedBy.frameworks.push(fw);
}
}
}
// Match by explicitly requested tags
if (options.tags && options.tags.length > 0) {
const requestedTags = new Set(options.tags.map((t) => t.toLowerCase()));
for (const tag of learning.tags) {
if (requestedTags.has(tag.toLowerCase())) {
score += 20;
matchedBy.tags.push(tag);
}
}
}
// Match by current task keywords
if (options.currentTask) {
const taskKeywords = this.extractKeywords(options.currentTask);
const learningKeywords = [
...this.extractKeywords(learning.title),
...this.extractKeywords(learning.content),
...learning.tags,
];
const learningKeywordSet = new Set(learningKeywords.map((k) => k.toLowerCase()));
for (const kw of taskKeywords) {
if (learningKeywordSet.has(kw.toLowerCase())) {
score += 10;
if (!matchedBy.keywords.includes(kw)) {
matchedBy.keywords.push(kw);
}
}
}
}
// Match by patterns
if (learning.patterns && learning.patterns.length > 0) {
// Patterns are valuable - boost score
score += learning.patterns.length * 5;
matchedBy.patterns.push(...learning.patterns);
}
// Boost by effectiveness if known
if (learning.effectiveness !== undefined) {
score += (learning.effectiveness / 100) * 20;
}
// Boost by use count (popular learnings are likely valuable)
score += Math.min(learning.useCount * 2, 15);
// Boost recent learnings
const daysSinceUpdate = this.daysSince(learning.updatedAt);
if (daysSinceUpdate < 7) {
score += 10;
} else if (daysSinceUpdate < 30) {
score += 5;
}
// Cap score at 100
score = Math.min(score, 100);
// Estimate token count
const tokenEstimate = this.estimateTokens(learning, options.disclosureLevel || 'preview');
return {
relevanceScore: score,
matchedBy,
tokenEstimate,
};
}
/**
* Extract framework names from project context
*/
private extractFrameworkNames(): Set<string> {
const names = new Set<string>();
if (!this.projectContext?.stack) return names;
const stack = this.projectContext.stack;
const categories = [
stack.languages,
stack.frameworks,
stack.libraries,
stack.styling,
stack.testing,
stack.databases,
stack.tools,
stack.runtime,
];
for (const category of categories) {
for (const detection of category) {
names.add(detection.name.toLowerCase());
}
}
return names;
}
/**
* Extract keywords from text
*/
private extractKeywords(text: string): string[] {
return text
.toLowerCase()
.split(/[\s\-_.,;:!?()[\]{}'"]+/)
.filter((word) => word.length > 2 && !STOP_WORDS.has(word));
}
/**
* Calculate days since a date
*/
private daysSince(dateStr: string): number {
const date = new Date(dateStr);
const now = new Date();
const diffMs = now.getTime() - date.getTime();
return Math.floor(diffMs / (1000 * 60 * 60 * 24));
}
/**
* Estimate tokens for a learning
*/
private estimateTokens(
learning: Learning,
level: 'summary' | 'preview' | 'full'
): number {
switch (level) {
case 'summary':
return Math.ceil((learning.title.length + learning.tags.join(' ').length) * TOKENS_PER_CHAR);
case 'preview':
const excerpt = learning.content.slice(0, 200);
return Math.ceil(
(learning.title.length + excerpt.length + learning.tags.join(' ').length) * TOKENS_PER_CHAR
);
case 'full':
return Math.ceil(
(learning.title.length + learning.content.length + learning.tags.join(' ').length) *
TOKENS_PER_CHAR
);
}
}
/**
* Inject memories and return formatted content
*/
async inject(options: InjectionOptions = {}): Promise<InjectionResult> {
const opts = { ...DEFAULT_OPTIONS, ...options };
const allMemories = await this.getRelevantMemories(opts);
// Select memories within token budget
const selected: InjectedMemory[] = [];
let totalTokens = 0;
let truncated = 0;
for (const memory of allMemories) {
if (totalTokens + memory.tokenEstimate <= opts.maxTokens) {
selected.push(memory);
totalTokens += memory.tokenEstimate;
// Increment use count
if (memory.learning.scope === 'project') {
this.projectStore.incrementUseCount(memory.learning.id);
} else {
this.globalStore.incrementUseCount(memory.learning.id);
}
} else {
truncated++;
}
}
// Format the content
const formattedContent = this.formatMemories(selected, opts.disclosureLevel || 'preview');
return {
memories: selected,
formattedContent,
totalTokens,
stats: {
considered: this.projectStore.count() + (opts.includeGlobal ? this.globalStore.count() : 0),
matched: allMemories.length,
injected: selected.length,
truncated,
},
};
}
/**
* Inject memories formatted for a specific agent
*/
async injectForAgent(
agent: AgentType,
options: InjectionOptions = {}
): Promise<InjectionResult> {
const result = await this.inject(options);
// Reformat for specific agent
result.formattedContent = this.formatForAgent(result.memories, agent, options.disclosureLevel);
return result;
}
/**
* Format memories for display
*/
private formatMemories(
memories: InjectedMemory[],
level: 'summary' | 'preview' | 'full'
): string {
if (memories.length === 0) {
return '';
}
const lines: string[] = ['# Relevant Memories', ''];
for (const { learning, relevanceScore, matchedBy } of memories) {
lines.push(`## ${learning.title}`);
lines.push(`*Relevance: ${relevanceScore}% | Tags: ${learning.tags.join(', ')}*`);
if (matchedBy.frameworks.length > 0) {
lines.push(`*Matched frameworks: ${matchedBy.frameworks.join(', ')}*`);
}
lines.push('');
switch (level) {
case 'summary':
// Just title and tags (already shown above)
break;
case 'preview':
lines.push(learning.content.slice(0, 200) + (learning.content.length > 200 ? '...' : ''));
break;
case 'full':
lines.push(learning.content);
break;
}
lines.push('');
}
return lines.join('\n');
}
/**
* Format memories for a specific agent
*/
formatForAgent(
memories: InjectedMemory[],
agent: AgentType,
level: 'summary' | 'preview' | 'full' = 'preview'
): string {
if (memories.length === 0) {
return '';
}
switch (agent) {
case 'claude-code':
return this.formatForClaude(memories, level);
case 'cursor':
return this.formatForCursor(memories, level);
case 'codex':
case 'github-copilot':
return this.formatForCopilot(memories, level);
default:
return this.formatMemories(memories, level);
}
}
/**
* Format memories for Claude (XML tags)
*/
private formatForClaude(
memories: InjectedMemory[],
level: 'summary' | 'preview' | 'full'
): string {
const lines: string[] = ['<memories>'];
for (const { learning, relevanceScore } of memories) {
lines.push(` <memory relevance="${relevanceScore}" scope="${learning.scope}">`);
lines.push(` <title>${this.escapeXml(learning.title)}</title>`);
lines.push(` <tags>${learning.tags.join(', ')}</tags>`);
if (level !== 'summary') {
const content =
level === 'preview' ? learning.content.slice(0, 200) : learning.content;
lines.push(` <content>${this.escapeXml(content)}</content>`);
}
if (learning.frameworks && learning.frameworks.length > 0) {
lines.push(` <frameworks>${learning.frameworks.join(', ')}</frameworks>`);
}
lines.push(' </memory>');
}
lines.push('</memories>');
return lines.join('\n');
}
/**
* Format memories for Cursor (.mdc format)
*/
private formatForCursor(
memories: InjectedMemory[],
level: 'summary' | 'preview' | 'full'
): string {
const lines: string[] = [
'---',
'description: Relevant memories from previous sessions',
'globs:',
' - "**/*"',
'---',
'',
'# Session Memories',
'',
];
for (const { learning, relevanceScore } of memories) {
lines.push(`## ${learning.title}`);
lines.push('');
lines.push(`> Relevance: ${relevanceScore}% | Tags: ${learning.tags.join(', ')}`);
lines.push('');
if (level !== 'summary') {
const content =
level === 'preview'
? learning.content.slice(0, 200) + (learning.content.length > 200 ? '...' : '')
: learning.content;
lines.push(content);
lines.push('');
}
}
return lines.join('\n');
}
/**
* Format memories for Copilot/Codex (concise markdown)
*/
private formatForCopilot(
memories: InjectedMemory[],
level: 'summary' | 'preview' | 'full'
): string {
const lines: string[] = ['<!-- Session Memories -->'];
for (const { learning } of memories) {
lines.push(`### ${learning.title}`);
lines.push(`Tags: ${learning.tags.join(', ')}`);
if (level !== 'summary') {
const content =
level === 'preview' ? learning.content.slice(0, 150) : learning.content;
lines.push(content);
}
lines.push('');
}
return lines.join('\n');
}
/**
* Escape XML special characters
*/
private escapeXml(text: string): string {
return text
.replace(/&/g, '&amp;')
.replace(/</g, '&lt;')
.replace(/>/g, '&gt;')
.replace(/"/g, '&quot;')
.replace(/'/g, '&apos;');
}
/**
* Get memory summaries (for progressive disclosure)
*/
getSummaries(options: InjectionOptions = {}): MemorySummary[] {
const opts = { ...DEFAULT_OPTIONS, ...options };
const projectLearnings = this.projectStore.getAll();
const globalLearnings = opts.includeGlobal ? this.globalStore.getAll() : [];
const allLearnings = [...projectLearnings, ...globalLearnings];
return allLearnings.map((learning) => ({
id: learning.id,
title: learning.title,
tags: learning.tags,
relevance: this.scoreLearning(learning, opts).relevanceScore,
}));
}
/**
* Get memory previews (for progressive disclosure)
*/
getPreviews(ids: string[], options: InjectionOptions = {}): MemoryPreview[] {
const opts = { ...DEFAULT_OPTIONS, ...options };
const previews: MemoryPreview[] = [];
for (const id of ids) {
let learning = this.projectStore.getById(id);
if (!learning && opts.includeGlobal) {
learning = this.globalStore.getById(id);
}
if (learning) {
previews.push({
id: learning.id,
title: learning.title,
tags: learning.tags,
relevance: this.scoreLearning(learning, opts).relevanceScore,
excerpt: learning.content.slice(0, 200),
lastUsed: learning.lastUsed,
});
}
}
return previews;
}
/**
* Get full memories (for progressive disclosure)
*/
getFullMemories(ids: string[], options: InjectionOptions = {}): MemoryFull[] {
const opts = { ...DEFAULT_OPTIONS, ...options };
const fullMemories: MemoryFull[] = [];
for (const id of ids) {
let learning = this.projectStore.getById(id);
if (!learning && opts.includeGlobal) {
learning = this.globalStore.getById(id);
}
if (learning) {
fullMemories.push({
id: learning.id,
title: learning.title,
tags: learning.tags,
relevance: this.scoreLearning(learning, opts).relevanceScore,
excerpt: learning.content.slice(0, 200),
lastUsed: learning.lastUsed,
content: learning.content,
});
}
}
return fullMemories;
}
/**
* Search memories by query
*/
search(query: string, options: InjectionOptions = {}): InjectedMemory[] {
const opts = { ...DEFAULT_OPTIONS, ...options, currentTask: query };
const projectResults = this.projectStore.search(query);
const globalResults = opts.includeGlobal ? this.globalStore.search(query) : [];
const allResults = [...projectResults, ...globalResults];
return allResults
.map((learning) => ({
learning,
...this.scoreLearning(learning, opts),
}))
.filter((m) => m.relevanceScore >= opts.minRelevance)
.sort((a, b) => b.relevanceScore - a.relevanceScore)
.slice(0, opts.maxLearnings);
}
}
/**
* Common stop words to ignore in keyword extraction
*/
const STOP_WORDS = new Set([
'the',
'a',
'an',
'and',
'or',
'but',
'in',
'on',
'at',
'to',
'for',
'of',
'with',
'by',
'from',
'as',
'is',
'was',
'are',
'were',
'been',
'be',
'have',
'has',
'had',
'do',
'does',
'did',
'will',
'would',
'could',
'should',
'may',
'might',
'must',
'can',
'this',
'that',
'these',
'those',
'i',
'you',
'he',
'she',
'it',
'we',
'they',
'what',
'which',
'who',
'when',
'where',
'why',
'how',
'all',
'each',
'every',
'both',
'few',
'more',
'most',
'other',
'some',
'such',
'no',
'nor',
'not',
'only',
'own',
'same',
'so',
'than',
'too',
'very',
'just',
'also',
]);
/**
* Create a MemoryInjector instance
*/
export function createMemoryInjector(
projectPath: string,
projectName?: string,
projectContext?: ProjectContext
): MemoryInjector {
return new MemoryInjector(projectPath, projectName, projectContext);
}
+210
View File
@@ -0,0 +1,210 @@
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { homedir } from 'node:os';
import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
import { randomUUID } from 'node:crypto';
import type { Learning, LearningStoreData } from './types.js';
export class LearningStore {
private readonly filePath: string;
private readonly scope: 'project' | 'global';
private readonly projectName?: string;
private data: LearningStoreData | null = null;
constructor(
scope: 'project' | 'global',
projectPath?: string,
projectName?: string
) {
this.scope = scope;
this.projectName = projectName;
if (scope === 'project' && projectPath) {
this.filePath = join(projectPath, '.skillkit', 'memory', 'learnings.yaml');
} else {
this.filePath = join(homedir(), '.skillkit', 'memory', 'global.yaml');
}
}
private ensureDir(): void {
const dir = dirname(this.filePath);
if (!existsSync(dir)) {
mkdirSync(dir, { recursive: true });
}
}
private load(): LearningStoreData {
if (this.data) return this.data;
if (existsSync(this.filePath)) {
try {
const content = readFileSync(this.filePath, 'utf-8');
this.data = parseYaml(content) as LearningStoreData;
} catch {
this.data = this.createEmpty();
}
} else {
this.data = this.createEmpty();
}
return this.data;
}
private createEmpty(): LearningStoreData {
return {
version: 1,
learnings: [],
};
}
private save(): void {
this.ensureDir();
const content = stringifyYaml(this.data, { lineWidth: 0 });
writeFileSync(this.filePath, content, 'utf-8');
}
add(learning: Omit<Learning, 'id' | 'createdAt' | 'updatedAt' | 'useCount' | 'scope' | 'project'>): Learning {
const data = this.load();
const now = new Date().toISOString();
const newLearning: Learning = {
...learning,
id: randomUUID(),
createdAt: now,
updatedAt: now,
useCount: 0,
scope: this.scope,
project: this.projectName,
};
data.learnings.push(newLearning);
this.save();
return newLearning;
}
update(id: string, updates: Partial<Omit<Learning, 'id' | 'createdAt'>>): Learning | null {
const data = this.load();
const index = data.learnings.findIndex((l) => l.id === id);
if (index === -1) return null;
data.learnings[index] = {
...data.learnings[index],
...updates,
updatedAt: new Date().toISOString(),
};
this.save();
return data.learnings[index];
}
delete(id: string): boolean {
const data = this.load();
const index = data.learnings.findIndex((l) => l.id === id);
if (index === -1) return false;
data.learnings.splice(index, 1);
this.save();
return true;
}
getAll(): Learning[] {
return this.load().learnings;
}
getById(id: string): Learning | undefined {
return this.load().learnings.find((l) => l.id === id);
}
getByTags(tags: string[]): Learning[] {
const tagSet = new Set(tags.map((t) => t.toLowerCase()));
return this.load().learnings.filter((l) =>
l.tags.some((t) => tagSet.has(t.toLowerCase()))
);
}
getByFrameworks(frameworks: string[]): Learning[] {
const fwSet = new Set(frameworks.map((f) => f.toLowerCase()));
return this.load().learnings.filter((l) =>
l.frameworks?.some((f) => fwSet.has(f.toLowerCase()))
);
}
getRecent(count: number): Learning[] {
const learnings = this.load().learnings;
return [...learnings]
.sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime())
.slice(0, count);
}
getMostUsed(count: number): Learning[] {
const learnings = this.load().learnings;
return [...learnings].sort((a, b) => b.useCount - a.useCount).slice(0, count);
}
getMostEffective(count: number): Learning[] {
const learnings = this.load().learnings.filter((l) => l.effectiveness !== undefined);
return [...learnings]
.sort((a, b) => (b.effectiveness || 0) - (a.effectiveness || 0))
.slice(0, count);
}
incrementUseCount(id: string): void {
const data = this.load();
const learning = data.learnings.find((l) => l.id === id);
if (learning) {
learning.useCount += 1;
learning.lastUsed = new Date().toISOString();
this.save();
}
}
setEffectiveness(id: string, effectiveness: number): void {
const data = this.load();
const learning = data.learnings.find((l) => l.id === id);
if (learning) {
learning.effectiveness = Math.max(0, Math.min(100, effectiveness));
learning.updatedAt = new Date().toISOString();
this.save();
}
}
search(query: string): Learning[] {
const queryLower = query.toLowerCase();
const queryWords = queryLower.split(/\s+/).filter((w) => w.length > 2);
return this.load().learnings.filter((l) => {
const titleMatch = l.title.toLowerCase().includes(queryLower);
const contentMatch = l.content.toLowerCase().includes(queryLower);
const tagMatch = l.tags.some((t) => t.toLowerCase().includes(queryLower));
const wordMatch = queryWords.some(
(word) =>
l.title.toLowerCase().includes(word) ||
l.content.toLowerCase().includes(word)
);
return titleMatch || contentMatch || tagMatch || wordMatch;
});
}
count(): number {
return this.load().learnings.length;
}
clear(): void {
this.data = this.createEmpty();
this.save();
}
exists(): boolean {
return existsSync(this.filePath);
}
getScope(): 'project' | 'global' {
return this.scope;
}
}
+281
View File
@@ -0,0 +1,281 @@
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
import type { Learning, MemoryIndex } from './types.js';
export class MemoryIndexStore {
private readonly filePath: string;
private data: MemoryIndex | null = null;
constructor(basePath: string, _isGlobal = false) {
// Both global and project use .skillkit subdirectory
// Global: ~/.skillkit/memory/index.yaml (basePath = homedir())
// Project: <projectPath>/.skillkit/memory/index.yaml (basePath = projectPath)
// Note: _isGlobal kept for API compatibility but basePath determines the actual path
this.filePath = join(basePath, '.skillkit', 'memory', 'index.yaml');
}
private ensureDir(): void {
const dir = dirname(this.filePath);
if (!existsSync(dir)) {
mkdirSync(dir, { recursive: true });
}
}
private load(): MemoryIndex {
if (this.data) return this.data;
if (existsSync(this.filePath)) {
try {
const content = readFileSync(this.filePath, 'utf-8');
this.data = parseYaml(content) as MemoryIndex;
} catch {
this.data = this.createEmpty();
}
} else {
this.data = this.createEmpty();
}
return this.data;
}
private createEmpty(): MemoryIndex {
return {
version: 1,
lastUpdated: new Date().toISOString(),
entries: {},
tags: {},
};
}
private save(): void {
this.ensureDir();
if (this.data) {
this.data.lastUpdated = new Date().toISOString();
}
const content = stringifyYaml(this.data, { lineWidth: 0 });
writeFileSync(this.filePath, content, 'utf-8');
}
private extractKeywords(text: string): string[] {
// Extract meaningful keywords from text
const stopWords = new Set([
'a', 'an', 'the', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for',
'of', 'with', 'by', 'from', 'is', 'are', 'was', 'were', 'be', 'been',
'being', 'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would',
'could', 'should', 'may', 'might', 'must', 'can', 'this', 'that',
'these', 'those', 'it', 'its', 'i', 'you', 'we', 'they', 'he', 'she',
]);
const words = text
.toLowerCase()
.replace(/[^a-z0-9\s-]/g, ' ')
.split(/\s+/)
.filter((word) => word.length > 2 && !stopWords.has(word));
return [...new Set(words)];
}
indexLearning(learning: Learning): void {
const data = this.load();
// Extract keywords from title and content
const titleKeywords = this.extractKeywords(learning.title);
const contentKeywords = this.extractKeywords(learning.content);
const allKeywords = [...new Set([...titleKeywords, ...contentKeywords])];
// Index by keywords
for (const keyword of allKeywords) {
if (!data.entries[keyword]) {
data.entries[keyword] = [];
}
if (!data.entries[keyword].includes(learning.id)) {
data.entries[keyword].push(learning.id);
}
}
// Index by tags
for (const tag of learning.tags) {
const normalizedTag = tag.toLowerCase();
if (!data.tags[normalizedTag]) {
data.tags[normalizedTag] = [];
}
if (!data.tags[normalizedTag].includes(learning.id)) {
data.tags[normalizedTag].push(learning.id);
}
}
// Index by frameworks if present
if (learning.frameworks) {
for (const framework of learning.frameworks) {
const normalizedFw = framework.toLowerCase();
if (!data.tags[normalizedFw]) {
data.tags[normalizedFw] = [];
}
if (!data.tags[normalizedFw].includes(learning.id)) {
data.tags[normalizedFw].push(learning.id);
}
}
}
this.save();
}
removeLearning(learningId: string): void {
const data = this.load();
// Remove from keyword entries
for (const keyword of Object.keys(data.entries)) {
data.entries[keyword] = data.entries[keyword].filter((id) => id !== learningId);
if (data.entries[keyword].length === 0) {
delete data.entries[keyword];
}
}
// Remove from tags
for (const tag of Object.keys(data.tags)) {
data.tags[tag] = data.tags[tag].filter((id) => id !== learningId);
if (data.tags[tag].length === 0) {
delete data.tags[tag];
}
}
this.save();
}
searchByKeywords(query: string): string[] {
const data = this.load();
const keywords = this.extractKeywords(query);
if (keywords.length === 0) return [];
// Find IDs that match any keyword
const matchCounts = new Map<string, number>();
for (const keyword of keywords) {
// Exact match
if (data.entries[keyword]) {
for (const id of data.entries[keyword]) {
matchCounts.set(id, (matchCounts.get(id) || 0) + 2);
}
}
// Partial match (keyword is substring of indexed word, but not exact match)
for (const [indexed, ids] of Object.entries(data.entries)) {
// Skip exact matches - they're already counted above with higher weight
if (indexed === keyword) continue;
if (indexed.includes(keyword) || keyword.includes(indexed)) {
for (const id of ids) {
matchCounts.set(id, (matchCounts.get(id) || 0) + 1);
}
}
}
}
// Sort by match count (most matches first)
return [...matchCounts.entries()]
.sort((a, b) => b[1] - a[1])
.map(([id]) => id);
}
searchByTags(tags: string[]): string[] {
const data = this.load();
const normalizedTags = tags.map((t) => t.toLowerCase());
const matchCounts = new Map<string, number>();
for (const tag of normalizedTags) {
if (data.tags[tag]) {
for (const id of data.tags[tag]) {
matchCounts.set(id, (matchCounts.get(id) || 0) + 1);
}
}
}
// Sort by match count
return [...matchCounts.entries()]
.sort((a, b) => b[1] - a[1])
.map(([id]) => id);
}
search(query: string, tags?: string[]): string[] {
const keywordResults = this.searchByKeywords(query);
const tagResults = tags ? this.searchByTags(tags) : [];
if (!tags || tags.length === 0) {
return keywordResults;
}
if (!query || query.trim().length === 0) {
return tagResults;
}
// Combine results, prioritizing items that match both
const keywordSet = new Set(keywordResults);
const tagSet = new Set(tagResults);
const both: string[] = [];
const keywordOnly: string[] = [];
const tagOnly: string[] = [];
for (const id of keywordResults) {
if (tagSet.has(id)) {
both.push(id);
} else {
keywordOnly.push(id);
}
}
for (const id of tagResults) {
if (!keywordSet.has(id)) {
tagOnly.push(id);
}
}
return [...both, ...keywordOnly, ...tagOnly];
}
getAllTags(): string[] {
const data = this.load();
return Object.keys(data.tags).sort();
}
getTagCounts(): Record<string, number> {
const data = this.load();
const counts: Record<string, number> = {};
for (const [tag, ids] of Object.entries(data.tags)) {
counts[tag] = ids.length;
}
return counts;
}
rebuildIndex(learnings: Learning[]): void {
// Clear existing index
this.data = this.createEmpty();
// Re-index all learnings
for (const learning of learnings) {
this.indexLearning(learning);
}
this.save();
}
clear(): void {
this.data = this.createEmpty();
this.save();
}
exists(): boolean {
return existsSync(this.filePath);
}
getStats(): { keywords: number; tags: number; lastUpdated: string } {
const data = this.load();
return {
keywords: Object.keys(data.entries).length,
tags: Object.keys(data.tags).length,
lastUpdated: data.lastUpdated,
};
}
}
@@ -0,0 +1,168 @@
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
import { randomUUID } from 'node:crypto';
import type {
Observation,
ObservationContent,
ObservationStoreData,
ObservationType,
} from './types.js';
import type { AgentType } from '../types.js';
export class ObservationStore {
private readonly filePath: string;
private data: ObservationStoreData | null = null;
private sessionId: string;
constructor(projectPath: string, sessionId?: string) {
this.filePath = join(projectPath, '.skillkit', 'memory', 'observations.yaml');
this.sessionId = sessionId || randomUUID();
}
private ensureDir(): void {
const dir = dirname(this.filePath);
if (!existsSync(dir)) {
mkdirSync(dir, { recursive: true });
}
}
private load(): ObservationStoreData {
if (this.data) return this.data;
if (existsSync(this.filePath)) {
try {
const content = readFileSync(this.filePath, 'utf-8');
this.data = parseYaml(content) as ObservationStoreData;
if (this.data.sessionId !== this.sessionId) {
this.data.sessionId = this.sessionId;
this.data.observations = [];
}
} catch {
this.data = this.createEmpty();
}
} else {
this.data = this.createEmpty();
}
return this.data;
}
private createEmpty(): ObservationStoreData {
return {
version: 1,
sessionId: this.sessionId,
observations: [],
};
}
private save(): void {
this.ensureDir();
const content = stringifyYaml(this.data, { lineWidth: 0 });
writeFileSync(this.filePath, content, 'utf-8');
}
add(
type: ObservationType,
content: ObservationContent,
agent: AgentType,
relevance = 50
): Observation {
const data = this.load();
const observation: Observation = {
id: randomUUID(),
timestamp: new Date().toISOString(),
sessionId: this.sessionId,
agent,
type,
content,
relevance,
};
data.observations.push(observation);
this.save();
return observation;
}
getAll(): Observation[] {
return this.load().observations;
}
getByType(type: ObservationType): Observation[] {
return this.load().observations.filter((o) => o.type === type);
}
getByRelevance(minRelevance: number): Observation[] {
return this.load().observations.filter((o) => o.relevance >= minRelevance);
}
getRecent(count: number): Observation[] {
const observations = this.load().observations;
return observations.slice(-count);
}
getUncompressed(compressedIds: string[]): Observation[] {
const compressedSet = new Set(compressedIds);
return this.load().observations.filter((o) => !compressedSet.has(o.id));
}
count(): number {
return this.load().observations.length;
}
clear(): void {
this.data = this.createEmpty();
this.save();
}
getById(id: string): Observation | undefined {
return this.load().observations.find((o) => o.id === id);
}
getByIds(ids: string[]): Observation[] {
const idSet = new Set(ids);
return this.load().observations.filter((o) => idSet.has(o.id));
}
getSessionId(): string {
return this.sessionId;
}
setSessionId(sessionId: string): void {
this.sessionId = sessionId;
if (this.data) {
this.data.sessionId = sessionId;
}
}
exists(): boolean {
return existsSync(this.filePath);
}
delete(id: string): boolean {
const data = this.load();
const index = data.observations.findIndex((o) => o.id === id);
if (index === -1) return false;
data.observations.splice(index, 1);
this.save();
return true;
}
deleteMany(ids: string[]): number {
const idSet = new Set(ids);
const data = this.load();
const initialLength = data.observations.length;
data.observations = data.observations.filter((o) => !idSet.has(o.id));
if (data.observations.length !== initialLength) {
this.save();
}
return initialLength - data.observations.length;
}
}
+636
View File
@@ -0,0 +1,636 @@
/**
* Memory Observer
*
* Captures observations during skill execution and stores them in the ObservationStore.
* Provides intelligent filtering to capture only significant events.
*/
import type { AgentType } from '../types.js';
import type { ExecutionProgressEvent } from '../executor/engine.js';
import type { ObservationType, ObservationContent, Observation } from './types.js';
import { ObservationStore } from './observation-store.js';
/**
* Event types that can be observed
*/
export type ObservableEventType =
| 'task_start'
| 'task_complete'
| 'task_failed'
| 'checkpoint_reached'
| 'checkpoint_decision'
| 'verification_passed'
| 'verification_failed'
| 'file_modified'
| 'error_encountered'
| 'solution_applied'
| 'execution_start'
| 'execution_complete'
| 'execution_paused';
/**
* Observable event structure
*/
export interface ObservableEvent {
type: ObservableEventType;
timestamp: string;
skillName?: string;
taskId?: string;
taskName?: string;
taskAction?: string;
files?: string[];
error?: string;
output?: string;
decision?: string;
context?: string;
}
/**
* Observer configuration
*/
export interface MemoryObserverConfig {
/** Minimum relevance score to store (0-100) */
minRelevance?: number;
/** Whether to capture task starts */
captureTaskStarts?: boolean;
/** Whether to capture checkpoints */
captureCheckpoints?: boolean;
/** Whether to capture file modifications */
captureFileModifications?: boolean;
/** Whether to capture errors */
captureErrors?: boolean;
/** Whether to capture solutions */
captureSolutions?: boolean;
/** Custom relevance scorer */
relevanceScorer?: (event: ObservableEvent) => number;
}
const DEFAULT_CONFIG: Required<Omit<MemoryObserverConfig, 'relevanceScorer'>> = {
minRelevance: 30,
captureTaskStarts: false, // Task starts are usually low-value
captureCheckpoints: true,
captureFileModifications: true,
captureErrors: true,
captureSolutions: true,
};
/**
* Memory Observer
*
* Captures and filters observations during skill execution.
*/
export class MemoryObserver {
private store: ObservationStore;
private config: Required<Omit<MemoryObserverConfig, 'relevanceScorer'>> & {
relevanceScorer?: (event: ObservableEvent) => number;
};
private currentAgent: AgentType = 'claude-code';
private currentSkillName?: string;
private pendingErrors: Map<string, ObservableEvent> = new Map();
constructor(projectPath: string, sessionId?: string, config?: MemoryObserverConfig) {
this.store = new ObservationStore(projectPath, sessionId);
this.config = { ...DEFAULT_CONFIG, ...config };
}
/**
* Set the current agent being used
*/
setAgent(agent: AgentType): void {
this.currentAgent = agent;
}
/**
* Set the current skill being executed
*/
setSkillName(skillName: string): void {
this.currentSkillName = skillName;
}
/**
* Get the underlying observation store
*/
getStore(): ObservationStore {
return this.store;
}
/**
* Observe an event and potentially store it
*/
observe(event: ObservableEvent): Observation | null {
// Check if we should capture this event type
if (!this.shouldCapture(event)) {
return null;
}
// Classify the event into an observation type
const observationType = this.classifyEvent(event);
// Extract content from the event
const content = this.extractContent(event);
// Score relevance
const relevance = this.scoreRelevance(event);
// Check minimum relevance threshold
if (relevance < this.config.minRelevance) {
return null;
}
// Store the observation
return this.store.add(observationType, content, this.currentAgent, relevance);
}
/**
* Create an observation callback for the SkillExecutionEngine
*/
createProgressCallback(): (event: ExecutionProgressEvent) => void {
return (progressEvent: ExecutionProgressEvent) => {
const observableEvent = this.convertProgressEvent(progressEvent);
if (observableEvent) {
this.observe(observableEvent);
}
};
}
/**
* Convert ExecutionProgressEvent to ObservableEvent
*/
private convertProgressEvent(event: ExecutionProgressEvent): ObservableEvent | null {
const baseEvent = {
timestamp: new Date().toISOString(),
skillName: this.currentSkillName,
taskId: event.taskId,
taskName: event.taskName,
};
switch (event.type) {
case 'task_start':
return {
...baseEvent,
type: 'task_start',
context: `Starting task ${event.taskIndex !== undefined ? event.taskIndex + 1 : ''} of ${event.totalTasks || '?'}`,
};
case 'task_complete':
if (event.status === 'failed') {
return {
...baseEvent,
type: 'task_failed',
error: event.error,
context: event.message,
};
}
return {
...baseEvent,
type: 'task_complete',
output: event.message,
context: `Completed task ${event.taskIndex !== undefined ? event.taskIndex + 1 : ''} of ${event.totalTasks || '?'}`,
};
case 'checkpoint':
return {
...baseEvent,
type: 'checkpoint_reached',
context: event.message,
};
case 'verification':
const passed = event.message?.includes('passed');
return {
...baseEvent,
type: passed ? 'verification_passed' : 'verification_failed',
context: event.message,
error: passed ? undefined : event.message,
};
case 'complete':
return {
...baseEvent,
type: 'execution_complete',
context: event.message,
error: event.status === 'failed' ? event.message : undefined,
};
default:
return null;
}
}
/**
* Record a file modification event
*/
recordFileModification(files: string[], context: string): Observation | null {
return this.observe({
type: 'file_modified',
timestamp: new Date().toISOString(),
skillName: this.currentSkillName,
files,
context,
});
}
/**
* Record an error event
*/
recordError(error: string, context: string, taskId?: string): Observation | null {
const event: ObservableEvent = {
type: 'error_encountered',
timestamp: new Date().toISOString(),
skillName: this.currentSkillName,
taskId,
error,
context,
};
// Store pending error for potential solution matching
const errorKey = this.generateErrorKey(error);
this.pendingErrors.set(errorKey, event);
return this.observe(event);
}
/**
* Record a solution event (potentially matching a previous error)
*/
recordSolution(solution: string, context: string, relatedError?: string): Observation | null {
const event: ObservableEvent = {
type: 'solution_applied',
timestamp: new Date().toISOString(),
skillName: this.currentSkillName,
output: solution,
context,
error: relatedError,
};
// If we can match this to a pending error, increase relevance
if (relatedError) {
const errorKey = this.generateErrorKey(relatedError);
this.pendingErrors.delete(errorKey);
}
return this.observe(event);
}
/**
* Record a decision event
*/
recordDecision(decision: string, options: string[], context: string): Observation | null {
return this.observe({
type: 'checkpoint_decision',
timestamp: new Date().toISOString(),
skillName: this.currentSkillName,
decision,
context: `Decision: ${decision} (options: ${options.join(', ')}). Context: ${context}`,
});
}
/**
* Record execution start
*/
recordExecutionStart(skillName: string, agent: AgentType): Observation | null {
this.currentSkillName = skillName;
this.currentAgent = agent;
return this.observe({
type: 'execution_start',
timestamp: new Date().toISOString(),
skillName,
context: `Started execution of skill "${skillName}" with agent "${agent}"`,
});
}
/**
* Record execution pause
*/
recordExecutionPause(reason?: string): Observation | null {
return this.observe({
type: 'execution_paused',
timestamp: new Date().toISOString(),
skillName: this.currentSkillName,
context: reason || 'Execution paused',
});
}
/**
* Check if we should capture this event type
*/
private shouldCapture(event: ObservableEvent): boolean {
switch (event.type) {
case 'task_start':
return this.config.captureTaskStarts;
case 'checkpoint_reached':
case 'checkpoint_decision':
return this.config.captureCheckpoints;
case 'file_modified':
return this.config.captureFileModifications;
case 'error_encountered':
case 'task_failed':
case 'verification_failed':
return this.config.captureErrors;
case 'solution_applied':
return this.config.captureSolutions;
default:
return true;
}
}
/**
* Classify event into observation type
*/
private classifyEvent(event: ObservableEvent): ObservationType {
switch (event.type) {
case 'error_encountered':
case 'task_failed':
case 'verification_failed':
return 'error';
case 'solution_applied':
return 'solution';
case 'checkpoint_decision':
return 'decision';
case 'file_modified':
return 'file_change';
case 'execution_paused':
case 'checkpoint_reached':
return 'checkpoint';
case 'task_start':
case 'task_complete':
case 'verification_passed':
case 'execution_start':
case 'execution_complete':
default:
return 'tool_use';
}
}
/**
* Extract content from event
*/
private extractContent(event: ObservableEvent): ObservationContent {
const content: ObservationContent = {
action: this.getActionDescription(event),
context: event.context || this.generateContext(event),
};
if (event.output) {
content.result = event.output;
}
if (event.files && event.files.length > 0) {
content.files = event.files;
}
if (event.error) {
content.error = event.error;
}
if (event.type === 'solution_applied' && event.output) {
content.solution = event.output;
}
// Generate tags based on event
content.tags = this.generateTags(event);
return content;
}
/**
* Get action description from event
*/
private getActionDescription(event: ObservableEvent): string {
switch (event.type) {
case 'task_start':
return `Started task: ${event.taskName || 'unknown'}`;
case 'task_complete':
return `Completed task: ${event.taskName || 'unknown'}`;
case 'task_failed':
return `Task failed: ${event.taskName || 'unknown'}`;
case 'checkpoint_reached':
return `Checkpoint: ${event.taskName || 'unknown'}`;
case 'checkpoint_decision':
return `Decision made: ${event.decision || 'unknown'}`;
case 'verification_passed':
return `Verification passed: ${event.taskName || 'unknown'}`;
case 'verification_failed':
return `Verification failed: ${event.taskName || 'unknown'}`;
case 'file_modified':
return `Modified files: ${event.files?.join(', ') || 'unknown'}`;
case 'error_encountered':
return `Error: ${event.error?.slice(0, 100) || 'unknown'}`;
case 'solution_applied':
return `Solution applied: ${event.output?.slice(0, 100) || 'unknown'}`;
case 'execution_start':
return `Started skill: ${event.skillName || 'unknown'}`;
case 'execution_complete':
return `Completed skill: ${event.skillName || 'unknown'}`;
case 'execution_paused':
return `Paused skill: ${event.skillName || 'unknown'}`;
default:
return 'Unknown action';
}
}
/**
* Generate context if not provided
*/
private generateContext(event: ObservableEvent): string {
const parts: string[] = [];
if (event.skillName) {
parts.push(`Skill: ${event.skillName}`);
}
if (event.taskName) {
parts.push(`Task: ${event.taskName}`);
}
if (event.taskAction) {
parts.push(`Action: ${event.taskAction}`);
}
return parts.join(' | ') || 'No context available';
}
/**
* Generate tags for event
*/
private generateTags(event: ObservableEvent): string[] {
const tags: string[] = [];
// Add event type as tag
tags.push(event.type.replace(/_/g, '-'));
// Add skill name if present
if (event.skillName) {
tags.push(event.skillName.toLowerCase().replace(/[^a-z0-9-]/g, '-'));
}
// Add error-related tags
if (event.error) {
if (event.error.toLowerCase().includes('type')) tags.push('typescript');
if (event.error.toLowerCase().includes('import')) tags.push('imports');
if (event.error.toLowerCase().includes('null') || event.error.toLowerCase().includes('undefined'))
tags.push('null-check');
if (event.error.toLowerCase().includes('async') || event.error.toLowerCase().includes('await'))
tags.push('async');
}
// Add file-related tags
if (event.files) {
for (const file of event.files) {
if (file.endsWith('.ts') || file.endsWith('.tsx')) tags.push('typescript');
if (file.endsWith('.js') || file.endsWith('.jsx')) tags.push('javascript');
if (file.endsWith('.css') || file.endsWith('.scss')) tags.push('styles');
if (file.includes('test') || file.includes('spec')) tags.push('testing');
if (file.includes('component')) tags.push('components');
}
}
return [...new Set(tags)];
}
/**
* Score relevance of event
*/
private scoreRelevance(event: ObservableEvent): number {
// Use custom scorer if provided
if (this.config.relevanceScorer) {
return this.config.relevanceScorer(event);
}
// Default relevance scoring
let score = 50; // Base score
switch (event.type) {
// High relevance events
case 'error_encountered':
case 'task_failed':
score = 85;
break;
case 'solution_applied':
score = 90;
// Bonus if it matches a pending error
if (event.error) {
const errorKey = this.generateErrorKey(event.error);
if (this.pendingErrors.has(errorKey)) {
score = 95;
}
}
break;
case 'checkpoint_decision':
score = 75;
break;
case 'verification_failed':
score = 80;
break;
// Medium relevance events
case 'file_modified':
score = 60;
// More files = higher relevance
if (event.files && event.files.length > 3) {
score = 70;
}
break;
case 'checkpoint_reached':
score = 55;
break;
case 'task_complete':
case 'verification_passed':
score = 50;
break;
// Lower relevance events
case 'task_start':
score = 30;
break;
case 'execution_start':
case 'execution_complete':
score = 40;
break;
case 'execution_paused':
score = 60;
break;
default:
score = 50;
}
// Adjust based on content richness
if (event.context && event.context.length > 100) {
score += 5;
}
if (event.files && event.files.length > 0) {
score += 5;
}
// Cap at 100
return Math.min(score, 100);
}
/**
* Generate a key for matching errors to solutions
*/
private generateErrorKey(error: string): string {
// Normalize error string for matching
return error
.toLowerCase()
.replace(/[0-9]+/g, 'N') // Replace numbers
.replace(/['"`]/g, '') // Remove quotes
.replace(/\s+/g, ' ') // Normalize whitespace
.slice(0, 100); // Limit length
}
/**
* Get session ID
*/
getSessionId(): string {
return this.store.getSessionId();
}
/**
* Get all observations
*/
getObservations(): Observation[] {
return this.store.getAll();
}
/**
* Get observation count
*/
getObservationCount(): number {
return this.store.count();
}
/**
* Clear all observations
*/
clear(): void {
this.store.clear();
this.pendingErrors.clear();
}
}
/**
* Create a MemoryObserver instance
*/
export function createMemoryObserver(
projectPath: string,
sessionId?: string,
config?: MemoryObserverConfig
): MemoryObserver {
return new MemoryObserver(projectPath, sessionId, config);
}
+117
View File
@@ -0,0 +1,117 @@
import type { AgentType } from '../types.js';
export type ObservationType =
| 'tool_use'
| 'decision'
| 'error'
| 'solution'
| 'pattern'
| 'file_change'
| 'checkpoint';
export interface ObservationContent {
action: string;
context: string;
result?: string;
files?: string[];
tags?: string[];
error?: string;
solution?: string;
}
export interface Observation {
id: string;
timestamp: string;
sessionId: string;
agent: AgentType;
type: ObservationType;
content: ObservationContent;
relevance: number;
}
export interface Learning {
id: string;
createdAt: string;
updatedAt: string;
source: 'session' | 'manual' | 'imported';
sourceObservations?: string[];
title: string;
content: string;
scope: 'project' | 'global';
project?: string;
tags: string[];
frameworks?: string[];
patterns?: string[];
useCount: number;
lastUsed?: string;
effectiveness?: number;
}
export interface MemoryIndex {
version: 1;
lastUpdated: string;
entries: Record<string, string[]>;
tags: Record<string, string[]>;
}
export interface MemorySummary {
id: string;
title: string;
tags: string[];
relevance: number;
}
export interface MemoryPreview extends MemorySummary {
excerpt: string;
lastUsed?: string;
}
export interface MemoryFull extends MemoryPreview {
content: string;
sourceObservations?: Observation[];
}
export interface ObservationStoreData {
version: 1;
sessionId: string;
observations: Observation[];
}
export interface LearningStoreData {
version: 1;
learnings: Learning[];
}
export interface MemoryConfig {
autoCompress: boolean;
compressionThreshold: number;
compressionModel?: string;
maxObservations: number;
maxLearnings: number;
}
export const DEFAULT_MEMORY_CONFIG: MemoryConfig = {
autoCompress: true,
compressionThreshold: 50,
maxObservations: 1000,
maxLearnings: 500,
};
export interface MemorySearchOptions {
query?: string;
tags?: string[];
scope?: 'project' | 'global' | 'all';
limit?: number;
minRelevance?: number;
}
export interface MemorySearchResult {
learning: Learning;
score: number;
matchedKeywords: string[];
matchedTags: string[];
}
+22
View File
@@ -0,0 +1,22 @@
/**
* Plugin System
*
* Enables extensibility through:
* - Custom translators for new agent formats
* - Custom providers for new skill sources
* - Custom commands for CLI extensions
* - Hooks for skill lifecycle events
*/
export { PluginManager, createPluginManager } from './manager.js';
export { PluginLoader, loadPlugin, loadPluginsFromDirectory } from './loader.js';
export type {
Plugin,
PluginMetadata,
PluginHooks,
TranslatorPlugin,
ProviderPlugin,
CommandPlugin,
PluginContext,
PluginConfig,
} from './types.js';
+332
View File
@@ -0,0 +1,332 @@
/**
* Plugin Loader
*
* Loads plugins from various sources:
* - Local files
* - npm packages
* - Git repositories
*/
import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
import { join, extname, basename, isAbsolute } from 'node:path';
import { pathToFileURL } from 'node:url';
import type { Plugin, PluginMetadata } from './types.js';
/**
* Plugin Loader class
*/
export class PluginLoader {
/**
* Load a plugin from a file path
*/
async loadFromFile(filePath: string): Promise<Plugin> {
if (!existsSync(filePath)) {
throw new Error(`Plugin file not found: ${filePath}`);
}
const ext = extname(filePath);
if (ext !== '.js' && ext !== '.mjs') {
throw new Error(`Unsupported plugin file type: ${ext}. Only .js and .mjs files are supported.`);
}
try {
// Use dynamic import for ES modules
const fileUrl = pathToFileURL(filePath).href;
const module = await import(fileUrl);
// Plugin can be default export or named export
const plugin = module.default || module.plugin;
if (!plugin || !plugin.metadata) {
throw new Error('Invalid plugin: missing metadata');
}
return this.validatePlugin(plugin);
} catch (err) {
throw new Error(
`Failed to load plugin from ${filePath}: ${
err instanceof Error ? err.message : 'Unknown error'
}`
);
}
}
/**
* Load a plugin from an npm package
*/
async loadFromPackage(packageName: string): Promise<Plugin> {
try {
// Try to resolve the package
const module = await import(packageName);
const plugin = module.default || module.plugin;
if (!plugin || !plugin.metadata) {
throw new Error('Invalid plugin: missing metadata');
}
return this.validatePlugin(plugin);
} catch (err) {
throw new Error(
`Failed to load plugin from package ${packageName}: ${
err instanceof Error ? err.message : 'Unknown error'
}`
);
}
}
/**
* Load a plugin from a JSON definition (for simple plugins)
*/
loadFromJson(jsonPath: string): Plugin {
if (!existsSync(jsonPath)) {
throw new Error(`Plugin JSON not found: ${jsonPath}`);
}
try {
const content = readFileSync(jsonPath, 'utf-8');
const data = JSON.parse(content);
if (!data.metadata) {
throw new Error('Invalid plugin JSON: missing metadata');
}
// JSON plugins can only define metadata, hooks need code
const plugin: Plugin = {
metadata: data.metadata,
};
return this.validatePlugin(plugin);
} catch (err) {
throw new Error(
`Failed to load plugin from ${jsonPath}: ${
err instanceof Error ? err.message : 'Unknown error'
}`
);
}
}
/**
* Scan a directory for plugins
*/
async scanDirectory(dirPath: string): Promise<PluginMetadata[]> {
if (!existsSync(dirPath)) {
return [];
}
const plugins: PluginMetadata[] = [];
const entries = readdirSync(dirPath);
for (const entry of entries) {
const fullPath = join(dirPath, entry);
// Guard against unreadable entries (permission denied, broken symlinks)
let stat;
try {
stat = statSync(fullPath);
} catch {
// Skip unreadable entries
continue;
}
if (stat.isDirectory()) {
// Check for package.json or plugin.json
const pkgPath = join(fullPath, 'package.json');
const pluginPath = join(fullPath, 'plugin.json');
if (existsSync(pkgPath)) {
try {
const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
// Validate required fields before pushing
if ((pkg.skillkitPlugin || pkg.keywords?.includes('skillkit-plugin')) &&
pkg.name && typeof pkg.name === 'string' &&
pkg.version && typeof pkg.version === 'string') {
plugins.push({
name: pkg.name,
version: pkg.version,
description: pkg.description,
author: pkg.author,
homepage: pkg.homepage,
});
}
} catch {
// Skip invalid packages
}
} else if (existsSync(pluginPath)) {
try {
const data = JSON.parse(readFileSync(pluginPath, 'utf-8'));
// Validate metadata has required fields
if (data.metadata &&
data.metadata.name && typeof data.metadata.name === 'string' &&
data.metadata.version && typeof data.metadata.version === 'string') {
plugins.push(data.metadata);
}
} catch {
// Skip invalid plugins
}
}
} else if (stat.isFile()) {
// Check for plugin files
const ext = extname(entry);
if (ext === '.js' || ext === '.mjs') {
const name = basename(entry, ext);
if (name.includes('plugin') || name.startsWith('skillkit-')) {
plugins.push({
name,
version: '0.0.0', // Unknown until loaded
description: `Plugin file: ${entry}`,
});
}
}
}
}
return plugins;
}
/**
* Validate a plugin structure
*/
private validatePlugin(plugin: Plugin): Plugin {
const { metadata } = plugin;
// Validate required metadata
if (!metadata.name) {
throw new Error('Plugin metadata must include a name');
}
if (!metadata.version) {
throw new Error('Plugin metadata must include a version');
}
// Validate name format (allow scoped npm names like @scope/name)
if (!/^(?:@[a-z0-9-]+\/)?[a-z0-9-]+$/.test(metadata.name)) {
throw new Error(
'Plugin name must be lowercase alphanumeric with hyphens only (scoped names like @scope/name are allowed)'
);
}
// Validate version format (loose semver check)
if (!/^\d+\.\d+\.\d+/.test(metadata.version)) {
throw new Error('Plugin version must be semver format (e.g., 1.0.0)');
}
// Validate translators
if (plugin.translators) {
for (const t of plugin.translators) {
if (!t.agentType || !t.translator) {
throw new Error('Translator plugin must include agentType and translator');
}
}
}
// Validate providers
if (plugin.providers) {
for (const p of plugin.providers) {
if (!p.providerName || !p.provider) {
throw new Error('Provider plugin must include providerName and provider');
}
}
}
// Validate commands
if (plugin.commands) {
for (const c of plugin.commands) {
if (!c.name || !c.handler) {
throw new Error('Command plugin must include name and handler');
}
}
}
return plugin;
}
}
/**
* Load a plugin from a file
*/
export async function loadPlugin(source: string): Promise<Plugin> {
const loader = new PluginLoader();
// Determine source type
// Check for local file paths: absolute, relative (./, .., paths with /), Windows paths, or tilde
const isLocalPath =
source.startsWith('.') || // ./, ../, .hidden
isAbsolute(source) || // /abs/path or C:\path
(source.includes('/') && !source.startsWith('@')) || // plugins/x.js (but not @scope/pkg)
source.includes('\\') || // Windows backslash
source.startsWith('~'); // ~/path
if (isLocalPath) {
// File path
if (source.endsWith('.json')) {
return loader.loadFromJson(source);
}
return loader.loadFromFile(source);
} else if (source.startsWith('@') || /^[a-z0-9-]+$/.test(source)) {
// npm package
return loader.loadFromPackage(source);
} else {
throw new Error(`Cannot determine plugin source type: ${source}`);
}
}
/**
* Load all plugins from a directory
*/
export async function loadPluginsFromDirectory(dirPath: string): Promise<Plugin[]> {
const loader = new PluginLoader();
const plugins: Plugin[] = [];
if (!existsSync(dirPath)) {
return plugins;
}
const entries = readdirSync(dirPath);
for (const entry of entries) {
const fullPath = join(dirPath, entry);
// Guard against unreadable entries (permission denied, broken symlinks)
let stat;
try {
stat = statSync(fullPath);
} catch {
// Skip unreadable entries
continue;
}
try {
if (stat.isDirectory()) {
// Try to load from directory (check ESM .mjs files first, then .js)
const indexMjsPath = join(fullPath, 'index.mjs');
const indexPath = join(fullPath, 'index.js');
const mainMjsPath = join(fullPath, 'plugin.mjs');
const mainPath = join(fullPath, 'plugin.js');
const jsonPath = join(fullPath, 'plugin.json');
if (existsSync(indexMjsPath)) {
plugins.push(await loader.loadFromFile(indexMjsPath));
} else if (existsSync(indexPath)) {
plugins.push(await loader.loadFromFile(indexPath));
} else if (existsSync(mainMjsPath)) {
plugins.push(await loader.loadFromFile(mainMjsPath));
} else if (existsSync(mainPath)) {
plugins.push(await loader.loadFromFile(mainPath));
} else if (existsSync(jsonPath)) {
plugins.push(loader.loadFromJson(jsonPath));
}
} else if (stat.isFile()) {
const ext = extname(entry);
if (ext === '.js' || ext === '.mjs') {
plugins.push(await loader.loadFromFile(fullPath));
} else if (ext === '.json' && entry.includes('plugin')) {
plugins.push(loader.loadFromJson(fullPath));
}
}
} catch (err) {
// Log but continue loading other plugins
console.warn(`Failed to load plugin from ${fullPath}: ${err}`);
}
}
return plugins;
}
+385
View File
@@ -0,0 +1,385 @@
/**
* Plugin Manager
*
* Manages plugin registration, lifecycle, and execution
*/
import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { join } from 'node:path';
import type {
Plugin,
PluginMetadata,
PluginHooks,
PluginContext,
PluginConfig,
CommandPlugin,
} from './types.js';
import type { AgentType } from '../types.js';
import type { CanonicalSkill, FormatTranslator } from '../translator/types.js';
import type { GitProviderAdapter } from '../providers/base.js';
const PLUGINS_DIR = '.skillkit/plugins';
const PLUGINS_CONFIG_FILE = 'plugins.json';
interface PluginsState {
version: number;
plugins: Record<string, {
enabled: boolean;
config: PluginConfig;
loadedAt?: string;
}>;
}
/**
* Plugin Manager class
*/
export class PluginManager {
private projectPath: string;
private plugins: Map<string, Plugin> = new Map();
private translators: Map<string, FormatTranslator> = new Map();
private providers: Map<string, GitProviderAdapter> = new Map();
private commands: Map<string, CommandPlugin> = new Map();
private hooks: Map<string, PluginHooks> = new Map();
private state: PluginsState;
private context: PluginContext;
constructor(projectPath: string) {
this.projectPath = projectPath;
this.state = this.loadState();
this.context = this.createContext();
}
/**
* Register a plugin
*/
async register(plugin: Plugin): Promise<void> {
const name = plugin.metadata.name;
// Check if already registered
if (this.plugins.has(name)) {
throw new Error(`Plugin "${name}" is already registered`);
}
// Check dependencies
if (plugin.metadata.dependencies) {
for (const dep of plugin.metadata.dependencies) {
if (!this.plugins.has(dep)) {
throw new Error(`Plugin "${name}" requires "${dep}" which is not loaded`);
}
}
}
// Initialize plugin
if (plugin.init) {
await plugin.init(this.context);
}
// Register translators
if (plugin.translators) {
for (const t of plugin.translators) {
this.translators.set(t.agentType, t.translator);
}
}
// Register providers
if (plugin.providers) {
for (const p of plugin.providers) {
this.providers.set(p.providerName, p.provider);
}
}
// Register commands
if (plugin.commands) {
for (const c of plugin.commands) {
this.commands.set(c.name, c);
if (c.aliases) {
for (const alias of c.aliases) {
this.commands.set(alias, c);
}
}
}
}
// Register hooks
if (plugin.hooks) {
this.hooks.set(name, plugin.hooks);
// Call onLoad hook
if (plugin.hooks.onLoad) {
await plugin.hooks.onLoad(this.context);
}
}
// Store plugin
this.plugins.set(name, plugin);
// Update state
this.state.plugins[name] = {
enabled: true,
config: {},
loadedAt: new Date().toISOString(),
};
this.saveState();
}
/**
* Unregister a plugin
*/
async unregister(name: string): Promise<void> {
const plugin = this.plugins.get(name);
if (!plugin) {
throw new Error(`Plugin "${name}" is not registered`);
}
// Call onUnload hook
const hooks = this.hooks.get(name);
if (hooks?.onUnload) {
await hooks.onUnload();
}
// Cleanup
if (plugin.destroy) {
await plugin.destroy();
}
// Remove translators
if (plugin.translators) {
for (const t of plugin.translators) {
this.translators.delete(t.agentType);
}
}
// Remove providers
if (plugin.providers) {
for (const p of plugin.providers) {
this.providers.delete(p.providerName);
}
}
// Remove commands
if (plugin.commands) {
for (const c of plugin.commands) {
this.commands.delete(c.name);
if (c.aliases) {
for (const alias of c.aliases) {
this.commands.delete(alias);
}
}
}
}
// Remove hooks
this.hooks.delete(name);
// Remove plugin
this.plugins.delete(name);
// Update state
delete this.state.plugins[name];
this.saveState();
}
/**
* Get a registered plugin
*/
getPlugin(name: string): Plugin | undefined {
return this.plugins.get(name);
}
/**
* Get all registered plugins
*/
getAllPlugins(): Plugin[] {
return Array.from(this.plugins.values());
}
/**
* Get plugin metadata for all plugins
*/
listPlugins(): PluginMetadata[] {
return this.getAllPlugins().map((p) => p.metadata);
}
/**
* Get a translator by agent type
*/
getTranslator(agentType: AgentType | string): FormatTranslator | undefined {
return this.translators.get(agentType);
}
/**
* Get all registered translators
*/
getAllTranslators(): Map<string, FormatTranslator> {
return new Map(this.translators);
}
/**
* Get a provider by name
*/
getProvider(name: string): GitProviderAdapter | undefined {
return this.providers.get(name);
}
/**
* Get all registered providers
*/
getAllProviders(): Map<string, GitProviderAdapter> {
return new Map(this.providers);
}
/**
* Get a command by name
*/
getCommand(name: string): CommandPlugin | undefined {
return this.commands.get(name);
}
/**
* Get all registered commands
*/
getAllCommands(): CommandPlugin[] {
return Array.from(new Set(this.commands.values()));
}
/**
* Execute hooks for an event
*/
async executeHook<K extends keyof PluginHooks>(
hookName: K,
...args: Parameters<NonNullable<PluginHooks[K]>>
): Promise<void> {
for (const [, hooks] of this.hooks) {
const hook = hooks[hookName];
if (hook) {
await (hook as (...args: unknown[]) => Promise<void>)(...args);
}
}
}
/**
* Execute beforeTranslate hooks (returns transformed skill)
*/
async executeBeforeTranslate(
skill: CanonicalSkill,
targetAgent: AgentType
): Promise<CanonicalSkill> {
let result = skill;
for (const [, hooks] of this.hooks) {
if (hooks.beforeTranslate) {
result = await hooks.beforeTranslate(result, targetAgent);
}
}
return result;
}
/**
* Execute afterTranslate hooks (returns transformed content)
*/
async executeAfterTranslate(
content: string,
targetAgent: AgentType
): Promise<string> {
let result = content;
for (const [, hooks] of this.hooks) {
if (hooks.afterTranslate) {
result = await hooks.afterTranslate(result, targetAgent);
}
}
return result;
}
/**
* Set plugin configuration
*/
setPluginConfig(name: string, config: PluginConfig): void {
if (!this.state.plugins[name]) {
this.state.plugins[name] = { enabled: true, config };
} else {
this.state.plugins[name].config = config;
}
this.saveState();
}
/**
* Get plugin configuration
*/
getPluginConfig(name: string): PluginConfig | undefined {
return this.state.plugins[name]?.config;
}
/**
* Enable a plugin
*/
enablePlugin(name: string): void {
if (this.state.plugins[name]) {
this.state.plugins[name].enabled = true;
this.saveState();
}
}
/**
* Disable a plugin
*/
disablePlugin(name: string): void {
if (this.state.plugins[name]) {
this.state.plugins[name].enabled = false;
this.saveState();
}
}
/**
* Check if plugin is enabled
*/
isPluginEnabled(name: string): boolean {
return this.state.plugins[name]?.enabled ?? true;
}
// Private helpers
private loadState(): PluginsState {
const statePath = join(this.projectPath, PLUGINS_DIR, PLUGINS_CONFIG_FILE);
if (existsSync(statePath)) {
try {
return JSON.parse(readFileSync(statePath, 'utf-8'));
} catch {
// Return default state on error
}
}
return { version: 1, plugins: {} };
}
private saveState(): void {
const pluginsDir = join(this.projectPath, PLUGINS_DIR);
if (!existsSync(pluginsDir)) {
mkdirSync(pluginsDir, { recursive: true });
}
const statePath = join(pluginsDir, PLUGINS_CONFIG_FILE);
writeFileSync(statePath, JSON.stringify(this.state, null, 2), 'utf-8');
}
private createContext(): PluginContext {
return {
projectPath: this.projectPath,
skillkitVersion: '1.4.0',
config: {},
log: {
info: (msg) => console.log(`[plugin] ${msg}`),
warn: (msg) => console.warn(`[plugin] ${msg}`),
error: (msg) => console.error(`[plugin] ${msg}`),
debug: (msg) => {
if (process.env.DEBUG) console.log(`[plugin:debug] ${msg}`);
},
},
getTranslator: (agentType) => this.translators.get(agentType),
getProvider: (name) => this.providers.get(name),
};
}
}
/**
* Create a plugin manager instance
*/
export function createPluginManager(projectPath: string): PluginManager {
return new PluginManager(projectPath);
}
+147
View File
@@ -0,0 +1,147 @@
/**
* Plugin System Types
*/
import type { AgentType } from '../types.js';
import type { CanonicalSkill, FormatTranslator } from '../translator/types.js';
import type { GitProviderAdapter } from '../providers/base.js';
/**
* Plugin metadata
*/
export interface PluginMetadata {
/** Unique plugin identifier */
name: string;
/** Plugin version (semver) */
version: string;
/** Human-readable description */
description?: string;
/** Plugin author */
author?: string;
/** Plugin homepage or repository URL */
homepage?: string;
/** Required SkillKit version */
skillkitVersion?: string;
/** Plugin dependencies */
dependencies?: string[];
/** Plugin keywords for discovery */
keywords?: string[];
}
/**
* Plugin lifecycle hooks
*/
export interface PluginHooks {
/** Called when a skill is installed */
onSkillInstall?: (skill: CanonicalSkill, agent: AgentType) => Promise<void>;
/** Called when a skill is removed */
onSkillRemove?: (skillName: string, agent: AgentType) => Promise<void>;
/** Called when skills are synced */
onSync?: (agents: AgentType[]) => Promise<void>;
/** Called before translation */
beforeTranslate?: (skill: CanonicalSkill, targetAgent: AgentType) => Promise<CanonicalSkill>;
/** Called after translation */
afterTranslate?: (content: string, targetAgent: AgentType) => Promise<string>;
/** Called when plugin is loaded */
onLoad?: (context: PluginContext) => Promise<void>;
/** Called when plugin is unloaded */
onUnload?: () => Promise<void>;
}
/**
* Translator plugin - adds support for new agent formats
*/
export interface TranslatorPlugin {
type: 'translator';
/** Agent type this translator handles */
agentType: AgentType | string;
/** The translator implementation */
translator: FormatTranslator;
}
/**
* Provider plugin - adds support for new skill sources
*/
export interface ProviderPlugin {
type: 'provider';
/** Provider name (e.g., 'bitbucket', 's3') */
providerName: string;
/** The provider implementation */
provider: GitProviderAdapter;
}
/**
* Command plugin - adds new CLI commands
*/
export interface CommandPlugin {
type: 'command';
/** Command name */
name: string;
/** Command aliases */
aliases?: string[];
/** Command description */
description: string;
/** Command options */
options?: Array<{
name: string;
description: string;
type: 'string' | 'boolean' | 'number';
required?: boolean;
default?: unknown;
}>;
/** Command handler */
handler: (args: Record<string, unknown>, context: PluginContext) => Promise<number>;
}
/**
* Plugin context passed to plugins
*/
export interface PluginContext {
/** Project path */
projectPath: string;
/** SkillKit version */
skillkitVersion: string;
/** Plugin configuration */
config: PluginConfig;
/** Logger instance */
log: {
info: (message: string) => void;
warn: (message: string) => void;
error: (message: string) => void;
debug: (message: string) => void;
};
/** Get a registered translator by agent type */
getTranslator: (agentType: AgentType) => FormatTranslator | undefined;
/** Get a registered provider by name */
getProvider: (name: string) => GitProviderAdapter | undefined;
}
/**
* Plugin configuration
*/
export interface PluginConfig {
/** Plugin-specific settings */
settings?: Record<string, unknown>;
/** Whether plugin is enabled */
enabled?: boolean;
}
/**
* Main plugin interface
*/
export interface Plugin {
/** Plugin metadata */
metadata: PluginMetadata;
/** Plugin hooks */
hooks?: PluginHooks;
/** Translator extensions */
translators?: TranslatorPlugin[];
/** Provider extensions */
providers?: ProviderPlugin[];
/** Command extensions */
commands?: CommandPlugin[];
/** Plugin initialization */
init?: (context: PluginContext) => Promise<void>;
/** Plugin cleanup */
destroy?: () => Promise<void>;
}
+274
View File
@@ -0,0 +1,274 @@
import { execSync } from 'node:child_process';
import { existsSync, rmSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { join } from 'node:path';
import { tmpdir, homedir } from 'node:os';
import { randomUUID } from 'node:crypto';
import type { SkillIndex, SkillSummary, IndexSource } from './types.js';
import { discoverSkills, extractFrontmatter } from '../skills.js';
/**
* Known skill repositories to index
*/
export const KNOWN_SKILL_REPOS = [
{ owner: 'anthropics', repo: 'courses', description: 'Anthropic official courses and skills' },
{ owner: 'vercel-labs', repo: 'ai-sdk-preview-internal-knowledge-base', description: 'Vercel AI SDK skills' },
{ owner: 'composioHQ', repo: 'awesome-claude-code-skills', description: 'Curated Claude Code skills' },
] as const;
/**
* Index file path
*/
export const INDEX_PATH = join(homedir(), '.skillkit', 'index.json');
export const INDEX_CACHE_HOURS = 24;
/**
* Fetch skills from a GitHub repository
*/
export async function fetchSkillsFromRepo(
owner: string,
repo: string
): Promise<{ skills: SkillSummary[]; error?: string }> {
const cloneUrl = `https://github.com/${owner}/${repo}.git`;
const tempDir = join(tmpdir(), `skillkit-fetch-${randomUUID()}`);
try {
// Shallow clone for speed
execSync(`git clone --depth 1 ${cloneUrl} ${tempDir}`, {
stdio: ['pipe', 'pipe', 'pipe'],
encoding: 'utf-8',
timeout: 60000, // 60 second timeout
});
// Discover skills in the cloned repo
const discoveredSkills = discoverSkills(tempDir);
const skills: SkillSummary[] = [];
for (const skill of discoveredSkills) {
const skillMdPath = join(skill.path, 'SKILL.md');
if (!existsSync(skillMdPath)) continue;
try {
const content = readFileSync(skillMdPath, 'utf-8');
const frontmatter = extractFrontmatter(content);
const summary: SkillSummary = {
name: skill.name,
description: skill.description || frontmatter?.description as string || 'No description',
source: `${owner}/${repo}`,
tags: (frontmatter?.tags as string[]) || [],
compatibility: {
frameworks: (frontmatter?.compatibility as Record<string, unknown>)?.frameworks as string[] || [],
languages: (frontmatter?.compatibility as Record<string, unknown>)?.languages as string[] || [],
libraries: (frontmatter?.compatibility as Record<string, unknown>)?.libraries as string[] || [],
},
popularity: 0,
quality: 50,
lastUpdated: new Date().toISOString(),
verified: owner === 'anthropics' || owner === 'vercel-labs',
};
skills.push(summary);
} catch {
// Skip skills that fail to parse
}
}
return { skills };
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
return { skills: [], error: `Failed to fetch ${owner}/${repo}: ${message}` };
} finally {
// Clean up temp directory
if (existsSync(tempDir)) {
try {
rmSync(tempDir, { recursive: true, force: true });
} catch {
// Ignore cleanup errors
}
}
}
}
/**
* Fetch skills from all known repositories and build index
*/
export async function buildSkillIndex(
repos: typeof KNOWN_SKILL_REPOS = KNOWN_SKILL_REPOS,
onProgress?: (message: string) => void
): Promise<{ index: SkillIndex; errors: string[] }> {
const allSkills: SkillSummary[] = [];
const sources: IndexSource[] = [];
const errors: string[] = [];
for (const { owner, repo } of repos) {
onProgress?.(`Fetching ${owner}/${repo}...`);
const result = await fetchSkillsFromRepo(owner, repo);
if (result.error) {
errors.push(result.error);
}
if (result.skills.length > 0) {
allSkills.push(...result.skills);
sources.push({
name: `${owner}/${repo}`,
url: `https://github.com/${owner}/${repo}`,
lastFetched: new Date().toISOString(),
skillCount: result.skills.length,
});
onProgress?.(` Found ${result.skills.length} skills`);
} else if (!result.error) {
onProgress?.(` No skills found`);
}
}
// Add fallback sample skills if no repos could be fetched
if (allSkills.length === 0) {
onProgress?.('No skills fetched, using sample index...');
allSkills.push(...getSampleSkills());
sources.push({
name: 'skillkit-samples',
url: 'https://github.com/skillkit/samples',
lastFetched: new Date().toISOString(),
skillCount: allSkills.length,
});
}
const index: SkillIndex = {
version: 1,
lastUpdated: new Date().toISOString(),
skills: allSkills,
sources,
};
return { index, errors };
}
/**
* Save skill index to cache
*/
export function saveIndex(index: SkillIndex): void {
const indexDir = join(homedir(), '.skillkit');
if (!existsSync(indexDir)) {
mkdirSync(indexDir, { recursive: true });
}
writeFileSync(INDEX_PATH, JSON.stringify(index, null, 2));
}
/**
* Load skill index from cache
*/
export function loadIndex(): SkillIndex | null {
if (!existsSync(INDEX_PATH)) {
return null;
}
try {
const content = readFileSync(INDEX_PATH, 'utf-8');
return JSON.parse(content) as SkillIndex;
} catch {
return null;
}
}
/**
* Check if index is stale
*/
export function isIndexStale(index: SkillIndex): boolean {
const lastUpdated = new Date(index.lastUpdated);
const hoursSinceUpdate = (Date.now() - lastUpdated.getTime()) / (1000 * 60 * 60);
return hoursSinceUpdate > INDEX_CACHE_HOURS;
}
/**
* Get index status
*/
export function getIndexStatus(): 'missing' | 'stale' | 'fresh' {
const index = loadIndex();
if (!index) return 'missing';
return isIndexStale(index) ? 'stale' : 'fresh';
}
/**
* Sample skills fallback (when repos can't be fetched)
*/
function getSampleSkills(): SkillSummary[] {
return [
{
name: 'react-best-practices',
description: 'Modern React patterns including Server Components, hooks best practices, and performance optimization',
source: 'skillkit/samples',
tags: ['react', 'frontend', 'typescript', 'nextjs', 'performance'],
compatibility: {
frameworks: ['react', 'nextjs'],
languages: ['typescript', 'javascript'],
libraries: [],
},
popularity: 1500,
quality: 95,
lastUpdated: new Date().toISOString(),
verified: true,
},
{
name: 'tailwind-patterns',
description: 'Tailwind CSS utility patterns, responsive design, and component styling best practices',
source: 'skillkit/samples',
tags: ['tailwind', 'css', 'styling', 'frontend', 'responsive'],
compatibility: {
frameworks: [],
languages: ['typescript', 'javascript'],
libraries: ['tailwindcss'],
},
popularity: 1200,
quality: 92,
lastUpdated: new Date().toISOString(),
verified: true,
},
{
name: 'typescript-strict-patterns',
description: 'TypeScript strict mode patterns, type safety, and advanced type utilities',
source: 'skillkit/samples',
tags: ['typescript', 'types', 'safety', 'patterns'],
compatibility: {
frameworks: [],
languages: ['typescript'],
libraries: [],
},
popularity: 900,
quality: 90,
lastUpdated: new Date().toISOString(),
verified: true,
},
{
name: 'security-best-practices',
description: 'Security patterns for web applications including XSS prevention, CSRF, and secure headers',
source: 'skillkit/samples',
tags: ['security', 'xss', 'csrf', 'headers', 'owasp'],
compatibility: {
frameworks: [],
languages: ['typescript', 'javascript', 'python'],
libraries: [],
},
popularity: 600,
quality: 95,
lastUpdated: new Date().toISOString(),
verified: true,
},
{
name: 'testing-patterns',
description: 'Testing patterns with Vitest/Jest including mocking, assertions, and test organization',
source: 'skillkit/samples',
tags: ['vitest', 'jest', 'testing', 'typescript', 'mocking', 'tdd'],
compatibility: {
frameworks: [],
languages: ['typescript', 'javascript'],
libraries: ['vitest', 'jest'],
},
popularity: 700,
quality: 86,
lastUpdated: new Date().toISOString(),
verified: false,
},
];
}
+12
View File
@@ -8,8 +8,20 @@
* - Framework/language/library detection
* - Task-based search
* - Freshness checking
* - Skill index fetching from GitHub repos
*/
export * from './types.js';
export * from './engine.js';
export * from './fetcher.js';
export { createRecommendationEngine, RecommendationEngine } from './engine.js';
export {
fetchSkillsFromRepo,
buildSkillIndex,
saveIndex,
loadIndex,
isIndexStale,
getIndexStatus,
KNOWN_SKILL_REPOS,
INDEX_PATH,
} from './fetcher.js';
+9
View File
@@ -0,0 +1,9 @@
/**
* Session Management Module
*
* Provides session state tracking for skill execution with pause/resume support.
*/
export * from './types.js';
export * from './manager.js';
export { SessionManager, createSessionManager } from './manager.js';
+349
View File
@@ -0,0 +1,349 @@
/**
* Session Manager
*
* Manages session state for skill execution with pause/resume support.
*/
import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'node:fs';
import { join } from 'node:path';
import { parse, stringify } from 'yaml';
import type {
SessionState,
CurrentExecution,
ExecutionHistory,
SessionTask,
TaskStatus,
} from './types.js';
import { SESSION_FILE } from './types.js';
/**
* Session Manager for tracking skill execution state
*/
export class SessionManager {
private projectPath: string;
private sessionPath: string;
private state: SessionState | null = null;
constructor(projectPath: string) {
this.projectPath = projectPath;
this.sessionPath = join(projectPath, '.skillkit', SESSION_FILE);
}
/**
* Get session file path
*/
getSessionPath(): string {
return this.sessionPath;
}
/**
* Load session state from disk
*/
load(): SessionState | null {
if (!existsSync(this.sessionPath)) {
return null;
}
try {
const content = readFileSync(this.sessionPath, 'utf-8');
this.state = parse(content) as SessionState;
return this.state;
} catch (error) {
console.error('Failed to load session:', error);
return null;
}
}
/**
* Save session state to disk
*/
save(): void {
if (!this.state) {
return;
}
const dir = join(this.projectPath, '.skillkit');
if (!existsSync(dir)) {
mkdirSync(dir, { recursive: true });
}
this.state.lastActivity = new Date().toISOString();
writeFileSync(this.sessionPath, stringify(this.state));
}
/**
* Initialize a new session
*/
init(): SessionState {
this.state = {
version: 1,
lastActivity: new Date().toISOString(),
projectPath: this.projectPath,
history: [],
decisions: [],
};
this.save();
return this.state;
}
/**
* Get current session state (load if needed)
*/
get(): SessionState | null {
if (!this.state) {
this.state = this.load();
}
return this.state;
}
/**
* Get or create session
*/
getOrCreate(): SessionState {
const state = this.get();
if (state) {
return state;
}
return this.init();
}
/**
* Start a new skill execution
*/
startExecution(skillName: string, skillSource: string, tasks: Omit<SessionTask, 'status'>[]): CurrentExecution {
const state = this.getOrCreate();
const execution: CurrentExecution = {
skillName,
skillSource,
currentStep: 0,
totalSteps: tasks.length,
status: 'running',
startedAt: new Date().toISOString(),
tasks: tasks.map((t) => ({
...t,
status: 'pending' as TaskStatus,
})),
};
state.currentExecution = execution;
this.save();
return execution;
}
/**
* Update task status
*/
updateTask(
taskId: string,
updates: Partial<Pick<SessionTask, 'status' | 'output' | 'error' | 'filesModified' | 'commitSha'>>
): void {
const state = this.get();
if (!state?.currentExecution) {
return;
}
const task = state.currentExecution.tasks.find((t) => t.id === taskId);
if (!task) {
return;
}
Object.assign(task, updates);
if (updates.status === 'in_progress' && !task.startedAt) {
task.startedAt = new Date().toISOString();
}
if (updates.status === 'completed' || updates.status === 'failed') {
task.completedAt = new Date().toISOString();
}
// Update current step
const completedCount = state.currentExecution.tasks.filter(
(t) => t.status === 'completed' || t.status === 'failed'
).length;
state.currentExecution.currentStep = completedCount;
this.save();
}
/**
* Advance to next task
*/
advanceToNextTask(): SessionTask | null {
const state = this.get();
if (!state?.currentExecution) {
return null;
}
const nextTask = state.currentExecution.tasks.find((t) => t.status === 'pending');
if (nextTask) {
nextTask.status = 'in_progress';
nextTask.startedAt = new Date().toISOString();
this.save();
}
return nextTask || null;
}
/**
* Pause current execution
*/
pause(): boolean {
const state = this.get();
if (!state?.currentExecution || state.currentExecution.status !== 'running') {
return false;
}
state.currentExecution.status = 'paused';
state.currentExecution.pausedAt = new Date().toISOString();
// Mark any in-progress tasks as paused
for (const task of state.currentExecution.tasks) {
if (task.status === 'in_progress') {
task.status = 'paused';
}
}
this.save();
return true;
}
/**
* Resume paused execution
*/
resume(): boolean {
const state = this.get();
if (!state?.currentExecution || state.currentExecution.status !== 'paused') {
return false;
}
state.currentExecution.status = 'running';
delete state.currentExecution.pausedAt;
// Resume paused tasks
for (const task of state.currentExecution.tasks) {
if (task.status === 'paused') {
task.status = 'in_progress';
}
}
this.save();
return true;
}
/**
* Complete current execution
*/
completeExecution(status: 'completed' | 'failed' | 'cancelled', error?: string): void {
const state = this.get();
if (!state?.currentExecution) {
return;
}
const execution = state.currentExecution;
const startTime = new Date(execution.startedAt).getTime();
const endTime = Date.now();
const historyEntry: ExecutionHistory = {
skillName: execution.skillName,
skillSource: execution.skillSource,
completedAt: new Date().toISOString(),
durationMs: endTime - startTime,
status,
commits: execution.tasks
.map((t) => t.commitSha)
.filter((sha): sha is string => !!sha),
filesModified: Array.from(
new Set(execution.tasks.flatMap((t) => t.filesModified || []))
),
error,
};
state.history.unshift(historyEntry);
delete state.currentExecution;
// Keep only last 50 history entries
if (state.history.length > 50) {
state.history = state.history.slice(0, 50);
}
this.save();
}
/**
* Record a user decision
*/
recordDecision(key: string, value: string, skillName?: string): void {
const state = this.getOrCreate();
// Update existing decision or add new one
const existing = state.decisions.find((d) => d.key === key);
if (existing) {
existing.value = value;
existing.madeAt = new Date().toISOString();
existing.skillName = skillName;
} else {
state.decisions.push({
key,
value,
madeAt: new Date().toISOString(),
skillName,
});
}
this.save();
}
/**
* Get a decision value
*/
getDecision(key: string): string | undefined {
const state = this.get();
return state?.decisions.find((d) => d.key === key)?.value;
}
/**
* Get execution history
*/
getHistory(limit?: number): ExecutionHistory[] {
const state = this.get();
if (!state) {
return [];
}
return limit ? state.history.slice(0, limit) : state.history;
}
/**
* Check if there's an active execution
*/
hasActiveExecution(): boolean {
const state = this.get();
return !!state?.currentExecution;
}
/**
* Check if execution is paused
*/
isPaused(): boolean {
const state = this.get();
return state?.currentExecution?.status === 'paused';
}
/**
* Clear session (delete file)
*/
clear(): void {
if (existsSync(this.sessionPath)) {
unlinkSync(this.sessionPath);
}
this.state = null;
}
}
/**
* Create a new session manager
*/
export function createSessionManager(projectPath: string): SessionManager {
return new SessionManager(projectPath);
}
+117
View File
@@ -0,0 +1,117 @@
/**
* Session State Types
*
* Types for managing skill execution sessions with pause/resume support.
*/
/**
* Status of a task in execution
*/
export type TaskStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'paused';
/**
* A single task within a skill execution
*/
export interface SessionTask {
/** Task identifier */
id: string;
/** Task name/description */
name: string;
/** Task type (auto, checkpoint:human-verify, checkpoint:decision, checkpoint:human-action) */
type: 'auto' | 'checkpoint:human-verify' | 'checkpoint:decision' | 'checkpoint:human-action';
/** Current status */
status: TaskStatus;
/** Start time */
startedAt?: string;
/** Completion time */
completedAt?: string;
/** Error message if failed */
error?: string;
/** Output/result of the task */
output?: string;
/** Files modified by this task */
filesModified?: string[];
/** Git commit SHA if committed */
commitSha?: string;
}
/**
* Current skill execution state
*/
export interface CurrentExecution {
/** Skill being executed */
skillName: string;
/** Skill source (repo) */
skillSource: string;
/** Current step/task index */
currentStep: number;
/** Total steps */
totalSteps: number;
/** Execution status */
status: 'running' | 'paused' | 'completed' | 'failed';
/** When execution started */
startedAt: string;
/** When execution was paused (if paused) */
pausedAt?: string;
/** Tasks in this execution */
tasks: SessionTask[];
}
/**
* Historical execution record
*/
export interface ExecutionHistory {
/** Skill name */
skillName: string;
/** Skill source */
skillSource: string;
/** When execution completed */
completedAt: string;
/** Duration in milliseconds */
durationMs: number;
/** Final status */
status: 'completed' | 'failed' | 'cancelled';
/** Git commits created */
commits: string[];
/** Files modified */
filesModified: string[];
/** Error if failed */
error?: string;
}
/**
* User decisions made during skill execution
*/
export interface SessionDecision {
/** Decision key/identifier */
key: string;
/** Decision value */
value: string;
/** When decision was made */
madeAt: string;
/** Skill that prompted the decision */
skillName?: string;
}
/**
* Full session state
*/
export interface SessionState {
/** Schema version */
version: 1;
/** Last activity timestamp */
lastActivity: string;
/** Project path this session is for */
projectPath: string;
/** Current execution (if any) */
currentExecution?: CurrentExecution;
/** Execution history */
history: ExecutionHistory[];
/** User decisions */
decisions: SessionDecision[];
}
/**
* Session state file path within .skillkit directory
*/
export const SESSION_FILE = 'session.yaml';
+332
View File
@@ -0,0 +1,332 @@
/**
* Skill Bundle
*
* Package multiple skills into a shareable bundle
*/
import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from 'node:fs';
import { join, basename, resolve, relative, dirname, sep } from 'node:path';
import { createHash } from 'node:crypto';
import type { BundleManifest } from './types.js';
import type { AgentType } from '../types.js';
const BUNDLE_VERSION = 1;
/**
* Skill Bundle class for creating and managing skill bundles
*/
export class SkillBundle {
private manifest: BundleManifest;
private skills: Map<string, string> = new Map(); // skillName -> content
constructor(name: string, author: string, description?: string) {
this.manifest = {
version: BUNDLE_VERSION,
name,
description,
author,
createdAt: new Date().toISOString(),
skills: [],
totalSize: 0,
};
}
/**
* Add a skill to the bundle
*/
addSkill(skillPath: string, agents?: AgentType[]): void {
const skillName = basename(skillPath);
// Check for duplicate skill names
if (this.skills.has(skillName)) {
throw new Error(`Skill "${skillName}" already exists in bundle`);
}
const content = this.readSkillContent(skillPath);
this.skills.set(skillName, content);
this.manifest.skills.push({
name: skillName,
path: skillName, // Store only the skill name, not the full path
agents: agents || this.detectAgents(skillPath),
});
this.manifest.totalSize += Buffer.byteLength(content, 'utf-8');
}
/**
* Remove a skill from the bundle
*/
removeSkill(skillName: string): boolean {
const skill = this.manifest.skills.find((s) => s.name === skillName);
if (!skill) return false;
const content = this.skills.get(skillName);
if (content) {
this.manifest.totalSize -= Buffer.byteLength(content, 'utf-8');
}
this.skills.delete(skillName);
this.manifest.skills = this.manifest.skills.filter((s) => s.name !== skillName);
return true;
}
/**
* Get bundle manifest
*/
getManifest(): BundleManifest {
return { ...this.manifest };
}
/**
* Get all skill names in bundle
*/
getSkillNames(): string[] {
return this.manifest.skills.map((s) => s.name);
}
/**
* Get skill content by name
*/
getSkillContent(skillName: string): string | undefined {
return this.skills.get(skillName);
}
/**
* Calculate bundle checksum
*/
getChecksum(): string {
const contents: string[] = [];
for (const [name, content] of this.skills.entries()) {
contents.push(`${name}:${content}`);
}
contents.sort();
return createHash('sha256').update(contents.join('\n')).digest('hex').slice(0, 12);
}
private readSkillContent(skillPath: string): string {
const contents: string[] = [];
const readDir = (dir: string, prefix = ''): void => {
const entries = readdirSync(dir);
for (const entry of entries) {
const fullPath = join(dir, entry);
const relativePath = prefix ? `${prefix}/${entry}` : entry;
const stat = statSync(fullPath);
if (stat.isDirectory()) {
readDir(fullPath, relativePath);
} else if (stat.isFile()) {
const content = readFileSync(fullPath, 'utf-8');
contents.push(`--- ${relativePath} ---\n${content}`);
}
}
};
if (statSync(skillPath).isDirectory()) {
readDir(skillPath);
} else {
contents.push(readFileSync(skillPath, 'utf-8'));
}
return contents.join('\n\n');
}
private detectAgents(skillPath: string): AgentType[] {
const agents: AgentType[] = [];
// Handle single-file skills - check if skillPath is a file
if (existsSync(skillPath) && statSync(skillPath).isFile()) {
const fileName = basename(skillPath).toLowerCase();
if (fileName === 'skill.md') {
return ['claude-code', 'codex', 'gemini-cli', 'universal'];
}
if (fileName === 'skill.mdc') {
return ['cursor'];
}
if (fileName === 'rules.md') {
return ['windsurf'];
}
return ['universal'];
}
// Directory-based skill detection
if (existsSync(join(skillPath, 'SKILL.md'))) {
agents.push('claude-code', 'codex', 'gemini-cli', 'universal');
}
if (existsSync(join(skillPath, 'skill.mdc'))) {
agents.push('cursor');
}
if (existsSync(join(skillPath, 'rules.md'))) {
agents.push('windsurf');
}
return agents.length > 0 ? agents : ['universal'];
}
}
/**
* Create a new skill bundle
*/
export function createSkillBundle(
name: string,
author: string,
description?: string
): SkillBundle {
return new SkillBundle(name, author, description);
}
/**
* Export a bundle to a file
*/
export function exportBundle(
bundle: SkillBundle,
outputPath: string
): { success: boolean; path?: string; error?: string } {
try {
const manifest = bundle.getManifest();
const exportData = {
manifest,
skills: {} as Record<string, string>,
};
for (const skill of manifest.skills) {
const content = bundle.getSkillContent(skill.name);
if (content) {
exportData.skills[skill.name] = content;
}
}
const dir = dirname(outputPath);
if (dir && !existsSync(dir)) {
mkdirSync(dir, { recursive: true });
}
// Export as JSON (could be changed to tarball for better compression)
writeFileSync(outputPath, JSON.stringify(exportData, null, 2), 'utf-8');
return { success: true, path: outputPath };
} catch (err) {
return {
success: false,
error: err instanceof Error ? err.message : 'Unknown error',
};
}
}
/**
* Import a bundle from a file
*/
export function importBundle(
bundlePath: string,
targetDir: string,
options: { overwrite?: boolean } = {}
): { success: boolean; imported: string[]; errors: string[] } {
const imported: string[] = [];
const errors: string[] = [];
try {
const content = readFileSync(bundlePath, 'utf-8');
const data = JSON.parse(content) as {
manifest: BundleManifest;
skills: Record<string, string>;
};
// Resolve targetDir to absolute path for consistent path containment checks
const absoluteTargetDir = resolve(targetDir);
for (const skill of data.manifest.skills) {
// Validate skill name to prevent path traversal attacks
if (!skill.name || skill.name.includes('/') || skill.name.includes('\\') ||
skill.name === '..' || skill.name === '.' || skill.name.startsWith('.')) {
errors.push(`Skill has invalid name: ${skill.name}`);
continue;
}
const skillContent = data.skills[skill.name];
if (!skillContent) {
errors.push(`Skill "${skill.name}" has no content in bundle`);
continue;
}
const skillDir = join(absoluteTargetDir, skill.name);
// Double-check the resolved path is within target directory (cross-platform)
const resolvedSkillDir = resolve(skillDir);
const relativeToTarget = relative(absoluteTargetDir, resolvedSkillDir);
if (relativeToTarget.startsWith('..') || relativeToTarget.startsWith(sep)) {
errors.push(`Skill "${skill.name}" would escape target directory`);
continue;
}
// Check if exists
if (existsSync(skillDir) && !options.overwrite) {
errors.push(`Skill "${skill.name}" already exists (use --overwrite)`);
continue;
}
// Create skill directory
if (!existsSync(skillDir)) {
mkdirSync(skillDir, { recursive: true });
}
// Parse and write skill files
const files = parseSkillContent(skillContent);
for (const [filePath, fileContent] of Object.entries(files)) {
// Validate path to prevent path traversal attacks
const fullPath = resolve(skillDir, filePath);
const relativeToSkill = relative(skillDir, fullPath);
// Check for path traversal (cross-platform)
if (relativeToSkill.startsWith('..') || relativeToSkill.startsWith(sep)) {
errors.push(`Skill "${skill.name}" contains invalid file path: ${filePath}`);
continue;
}
const fileDir = dirname(fullPath);
if (!existsSync(fileDir)) {
mkdirSync(fileDir, { recursive: true });
}
writeFileSync(fullPath, fileContent, 'utf-8');
}
imported.push(skill.name);
}
return { success: errors.length === 0, imported, errors };
} catch (err) {
errors.push(err instanceof Error ? err.message : 'Unknown error');
return { success: false, imported, errors };
}
}
/**
* Parse skill content back into individual files
*/
function parseSkillContent(content: string): Record<string, string> {
const files: Record<string, string> = {};
// Match file headers at start of string OR after newline
// This ensures the first file isn't dropped when content starts with "--- file ---"
const sections = content.split(/(?:^|\n)--- ([^\n]+) ---\n/);
// sections[0] is content before first header (empty if content starts with header)
// Then alternating: filePath, fileContent, filePath, fileContent, ...
let i = 1;
while (i < sections.length) {
const filePath = sections[i];
const fileContent = sections[i + 1] || '';
if (filePath && !filePath.startsWith('---')) {
files[filePath.trim()] = fileContent;
}
i += 2;
}
// If no file markers found, assume it's a single SKILL.md
if (Object.keys(files).length === 0 && content.trim()) {
files['SKILL.md'] = content;
}
return files;
}
+20
View File
@@ -0,0 +1,20 @@
/**
* Team Collaboration Module
*
* Enables sharing skills across team members via:
* - Git repositories (shared skill repos)
* - Team skill registries
* - Import/export of skill bundles
*/
export { TeamManager, createTeamManager } from './manager.js';
export { SkillBundle, createSkillBundle, exportBundle, importBundle } from './bundle.js';
export type {
TeamConfig,
TeamMember,
SharedSkill,
TeamRegistry,
BundleManifest,
ShareOptions,
ImportOptions,
} from './types.js';
+447
View File
@@ -0,0 +1,447 @@
/**
* Team Manager
*
* Manages team skill sharing and collaboration
*/
import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { join, dirname } from 'node:path';
import { execSync } from 'node:child_process';
import { parse as yamlParse, stringify as yamlStringify } from 'yaml';
import type {
TeamConfig,
TeamRegistry,
SharedSkill,
ShareOptions,
ImportOptions,
} from './types.js';
import type { AgentType } from '../types.js';
import { detectProvider } from '../providers/index.js';
const TEAM_CONFIG_FILE = 'team.yaml';
const TEAM_DIR = '.skillkit/team';
/**
* Team Manager for collaboration features
*/
export class TeamManager {
private projectPath: string;
private config: TeamConfig | null = null;
private registry: TeamRegistry | null = null;
constructor(projectPath: string) {
this.projectPath = projectPath;
}
/**
* Initialize team configuration
*/
async init(config: Omit<TeamConfig, 'teamId'>): Promise<TeamConfig> {
const teamId = this.generateTeamId();
const fullConfig: TeamConfig = {
...config,
teamId,
};
// Create team directory
const teamDir = join(this.projectPath, TEAM_DIR);
if (!existsSync(teamDir)) {
mkdirSync(teamDir, { recursive: true });
}
// Save config
this.saveConfig(fullConfig);
this.config = fullConfig;
// Initialize empty registry
const registry: TeamRegistry = {
version: 1,
teamId,
teamName: config.teamName,
skills: [],
createdAt: new Date().toISOString(),
updatedAt: new Date().toISOString(),
};
this.saveRegistry(registry);
this.registry = registry;
return fullConfig;
}
/**
* Load existing team configuration
*/
load(): TeamConfig | null {
const configPath = join(this.projectPath, TEAM_DIR, TEAM_CONFIG_FILE);
if (!existsSync(configPath)) {
return null;
}
try {
const content = readFileSync(configPath, 'utf-8');
this.config = this.parseYaml(content) as TeamConfig;
this.loadRegistry();
return this.config;
} catch {
return null;
}
}
/**
* Get current config
*/
getConfig(): TeamConfig | null {
return this.config;
}
/**
* Get current registry
*/
getRegistry(): TeamRegistry | null {
return this.registry;
}
/**
* Share a skill to the team registry
*/
async shareSkill(options: ShareOptions): Promise<SharedSkill> {
if (!this.config || !this.registry) {
throw new Error('Team not initialized. Run `skillkit team init` first.');
}
// Find the skill in local skills directory
const skillPath = this.findLocalSkill(options.skillName);
if (!skillPath) {
throw new Error(`Skill "${options.skillName}" not found locally.`);
}
// Read skill content and metadata
const skillMdPath = join(skillPath, 'SKILL.md');
const skillContent = existsSync(skillMdPath)
? readFileSync(skillMdPath, 'utf-8')
: '';
// Parse frontmatter for metadata
const metadata = this.extractFrontmatter(skillContent);
// Create shared skill entry
const shared: SharedSkill = {
name: options.skillName,
version: (metadata.version as string) || '1.0.0',
description: options.description || (metadata.description as string) || '',
author: this.getAuthor(),
sharedAt: new Date().toISOString(),
updatedAt: new Date().toISOString(),
source: `${this.config.registryUrl}#${options.skillName}`,
tags: options.tags || (metadata.tags as string[]) || [],
agents: options.agents || this.detectCompatibleAgents(skillPath),
downloads: 0,
};
// Check if skill already exists
const existingIndex = this.registry.skills.findIndex(
(s) => s.name === options.skillName
);
if (existingIndex >= 0) {
// Update existing
shared.sharedAt = this.registry.skills[existingIndex].sharedAt;
shared.downloads = this.registry.skills[existingIndex].downloads;
this.registry.skills[existingIndex] = shared;
} else {
// Add new
this.registry.skills.push(shared);
}
this.registry.updatedAt = new Date().toISOString();
this.saveRegistry(this.registry);
return shared;
}
/**
* List all shared skills in the team registry
*/
listSharedSkills(): SharedSkill[] {
return this.registry?.skills || [];
}
/**
* Search shared skills
*/
searchSkills(query: string): SharedSkill[] {
if (!this.registry) return [];
const lowerQuery = query.toLowerCase();
return this.registry.skills.filter(
(s) =>
s.name.toLowerCase().includes(lowerQuery) ||
s.description?.toLowerCase().includes(lowerQuery) ||
s.tags?.some((t) => t.toLowerCase().includes(lowerQuery))
);
}
/**
* Import a shared skill from the team registry
*/
async importSkill(
skillName: string,
options: ImportOptions = {}
): Promise<{ success: boolean; path?: string; error?: string }> {
if (!this.config || !this.registry) {
return { success: false, error: 'Team not initialized' };
}
const sharedSkill = this.registry.skills.find((s) => s.name === skillName);
if (!sharedSkill) {
return { success: false, error: `Skill "${skillName}" not found in team registry` };
}
// Check if skill exists locally
const localPath = this.findLocalSkill(skillName);
if (localPath && !options.overwrite) {
return {
success: false,
error: `Skill "${skillName}" already exists. Use --overwrite to replace.`,
};
}
if (options.dryRun) {
return {
success: true,
path: join(this.projectPath, '.skillkit', 'skills', skillName),
};
}
// Clone from registry source
try {
const provider = detectProvider(this.config.registryUrl);
if (!provider) {
return { success: false, error: 'Cannot detect provider for registry URL' };
}
// Build clone options with auth if available
const cloneOptions: { depth?: number; ssh?: boolean } = { depth: 1 };
if (this.config.auth?.type === 'ssh') {
cloneOptions.ssh = true;
}
const result = await provider.clone(this.config.registryUrl, skillName, cloneOptions);
if (!result.success) {
return { success: false, error: result.error };
}
// Update download count
sharedSkill.downloads = (sharedSkill.downloads || 0) + 1;
this.saveRegistry(this.registry);
return { success: true, path: result.path };
} catch (err) {
return {
success: false,
error: err instanceof Error ? err.message : 'Unknown error',
};
}
}
/**
* Sync with remote registry
*/
async sync(): Promise<{
added: string[];
updated: string[];
removed: string[];
}> {
if (!this.config) {
throw new Error('Team not initialized');
}
if (!this.registry) {
throw new Error('Team registry not loaded. Call load() first.');
}
const result = { added: [] as string[], updated: [] as string[], removed: [] as string[] };
try {
const provider = detectProvider(this.config.registryUrl);
if (!provider) {
throw new Error('Cannot detect provider for registry URL');
}
// Build clone options with auth if available
const cloneOptions: { depth?: number; ssh?: boolean } = { depth: 1 };
if (this.config.auth?.type === 'ssh') {
cloneOptions.ssh = true;
}
// Fetch remote registry
const fetchResult = await provider.clone(this.config.registryUrl, '', cloneOptions);
if (!fetchResult.success || !fetchResult.path) {
throw new Error(fetchResult.error || 'Failed to fetch remote registry');
}
// Read remote registry
const remoteRegistryPath = join(fetchResult.path, TEAM_DIR, 'registry.yaml');
if (existsSync(remoteRegistryPath)) {
const remoteContent = readFileSync(remoteRegistryPath, 'utf-8');
const remoteRegistry = this.parseYaml(remoteContent) as TeamRegistry;
// Merge registries
const localSkillNames = new Set(this.registry?.skills.map((s) => s.name) || []);
// Find added skills
for (const skill of remoteRegistry.skills) {
if (!localSkillNames.has(skill.name)) {
result.added.push(skill.name);
this.registry?.skills.push(skill);
} else {
// Check if updated
const local = this.registry?.skills.find((s) => s.name === skill.name);
if (local && new Date(skill.updatedAt) > new Date(local.updatedAt)) {
result.updated.push(skill.name);
Object.assign(local, skill);
}
}
}
// Find removed skills (optional - keep local for now)
// for (const skill of this.registry?.skills || []) {
// if (!remoteSkillNames.has(skill.name)) {
// result.removed.push(skill.name);
// }
// }
if (this.registry) {
this.registry.updatedAt = new Date().toISOString();
this.saveRegistry(this.registry);
}
}
// Clean up temp directory
if (fetchResult.tempRoot) {
const { rmSync } = await import('node:fs');
rmSync(fetchResult.tempRoot, { recursive: true, force: true });
}
} catch (err) {
throw new Error(`Sync failed: ${err instanceof Error ? err.message : 'Unknown error'}`);
}
return result;
}
/**
* Remove a skill from the team registry
*/
removeSkill(skillName: string): boolean {
if (!this.registry) return false;
const index = this.registry.skills.findIndex((s) => s.name === skillName);
if (index === -1) return false;
this.registry.skills.splice(index, 1);
this.registry.updatedAt = new Date().toISOString();
this.saveRegistry(this.registry);
return true;
}
// Private helpers
private generateTeamId(): string {
return `team-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
}
private saveConfig(config: TeamConfig): void {
const configPath = join(this.projectPath, TEAM_DIR, TEAM_CONFIG_FILE);
const dir = dirname(configPath);
if (!existsSync(dir)) {
mkdirSync(dir, { recursive: true });
}
writeFileSync(configPath, this.toYaml(config), 'utf-8');
}
private loadRegistry(): void {
const registryPath = join(this.projectPath, TEAM_DIR, 'registry.yaml');
if (existsSync(registryPath)) {
const content = readFileSync(registryPath, 'utf-8');
this.registry = this.parseYaml(content) as TeamRegistry;
}
}
private saveRegistry(registry: TeamRegistry): void {
const registryPath = join(this.projectPath, TEAM_DIR, 'registry.yaml');
writeFileSync(registryPath, this.toYaml(registry), 'utf-8');
}
private findLocalSkill(skillName: string): string | null {
const possiblePaths = [
join(this.projectPath, '.skillkit', 'skills', skillName),
join(this.projectPath, 'skills', skillName),
join(this.projectPath, '.claude', 'skills', skillName),
];
for (const p of possiblePaths) {
if (existsSync(p)) {
return p;
}
}
return null;
}
private getAuthor(): string {
// Try to get from git config
try {
const name = execSync('git config user.name', { encoding: 'utf-8' }).trim();
const email = execSync('git config user.email', { encoding: 'utf-8' }).trim();
return email ? `${name} <${email}>` : name;
} catch {
return 'Unknown';
}
}
private detectCompatibleAgents(skillPath: string): AgentType[] {
const agents: AgentType[] = [];
// Check for format-specific files
if (existsSync(join(skillPath, 'SKILL.md'))) {
agents.push('claude-code', 'codex', 'gemini-cli', 'universal');
}
if (existsSync(join(skillPath, 'skill.mdc'))) {
agents.push('cursor');
}
if (existsSync(join(skillPath, 'rules.md'))) {
agents.push('windsurf');
}
return agents.length > 0 ? agents : ['universal'];
}
private extractFrontmatter(content: string): Record<string, unknown> {
const match = content.match(/^---\n([\s\S]*?)\n---/);
if (!match) return {};
try {
return this.parseYaml(match[1]) as Record<string, unknown>;
} catch {
return {};
}
}
private parseYaml(content: string): unknown {
return yamlParse(content);
}
private toYaml(obj: unknown): string {
return yamlStringify(obj, { indent: 2 });
}
}
/**
* Create a team manager instance
*/
export function createTeamManager(projectPath: string): TeamManager {
return new TeamManager(projectPath);
}
+112
View File
@@ -0,0 +1,112 @@
/**
* Team Collaboration Types
*/
import type { AgentType } from '../types.js';
/**
* Team member information
*/
export interface TeamMember {
id: string;
name: string;
email?: string;
role: 'admin' | 'contributor' | 'viewer';
joinedAt: string;
}
/**
* Shared skill metadata
*/
export interface SharedSkill {
name: string;
version: string;
description?: string;
author: string;
sharedAt: string;
updatedAt: string;
source: string; // Git URL or registry path
tags?: string[];
agents: AgentType[];
downloads?: number;
rating?: number;
}
/**
* Team configuration
*/
export interface TeamConfig {
/** Team identifier */
teamId: string;
/** Team name */
teamName: string;
/** Team registry URL (git repo or registry endpoint) */
registryUrl: string;
/** Authentication method */
auth?: {
type: 'token' | 'ssh' | 'none';
token?: string;
keyPath?: string;
};
/** Auto-sync interval in minutes (0 = disabled) */
autoSyncInterval?: number;
/** Members list (for admin features) */
members?: TeamMember[];
}
/**
* Team registry containing shared skills
*/
export interface TeamRegistry {
version: number;
teamId: string;
teamName: string;
skills: SharedSkill[];
updatedAt: string;
createdAt: string;
}
/**
* Bundle manifest for exporting skills
*/
export interface BundleManifest {
version: number;
name: string;
description?: string;
author: string;
createdAt: string;
skills: {
name: string;
path: string;
agents: AgentType[];
}[];
totalSize: number;
}
/**
* Options for sharing a skill
*/
export interface ShareOptions {
/** Skill name to share */
skillName: string;
/** Description override */
description?: string;
/** Tags to add */
tags?: string[];
/** Target agents (default: all compatible) */
agents?: AgentType[];
/** Visibility level */
visibility?: 'team' | 'public';
}
/**
* Options for importing skills
*/
export interface ImportOptions {
/** Overwrite existing skills */
overwrite?: boolean;
/** Target agents to install for */
agents?: AgentType[];
/** Dry run mode */
dryRun?: boolean;
}
+42
View File
@@ -0,0 +1,42 @@
/**
* Skill Testing Framework
*
* Provides test case definitions and a test runner for skill verification.
*
* @example
* ```yaml
* # In skill frontmatter
* tests:
* - name: "Creates config file"
* assertions:
* - type: file_exists
* target: config.json
* - name: "Valid JSON output"
* assertions:
* - type: json_valid
* target: config.json
* - name: "Types check"
* assertions:
* - type: type_check
* ```
*/
export * from './types.js';
export * from './runner.js';
export {
runTestSuite,
createTestSuiteFromFrontmatter,
} from './runner.js';
export type {
TestAssertionType,
TestAssertion,
SkillTestCase,
SkillTestSuite,
AssertionResult,
TestCaseResult,
TestSuiteResult,
TestRunnerOptions,
TestProgressEvent,
} from './types.js';
File diff suppressed because it is too large Load Diff
+180
View File
@@ -0,0 +1,180 @@
/**
* Skill Testing Framework Types
*
* Define test cases in skill frontmatter for automated verification.
*/
/**
* Test assertion types
*/
export type TestAssertionType =
| 'file_exists'
| 'file_not_exists'
| 'file_contains'
| 'file_not_contains'
| 'file_matches'
| 'command_succeeds'
| 'command_fails'
| 'command_output_contains'
| 'json_valid'
| 'json_has_key'
| 'yaml_valid'
| 'type_check'
| 'lint_passes'
| 'test_passes'
| 'env_var_set'
| 'port_available'
| 'url_responds'
| 'custom';
/**
* Test assertion definition
*/
export interface TestAssertion {
/** Assertion type */
type: TestAssertionType;
/** Target file, command, or URL */
target?: string;
/** Expected value or pattern */
expected?: string | boolean | number;
/** Custom command for 'custom' type */
command?: string;
/** Timeout in milliseconds */
timeout?: number;
/** Error message on failure */
message?: string;
}
/**
* Test case definition
*/
export interface SkillTestCase {
/** Test name */
name: string;
/** Test description */
description?: string;
/** Assertions to run */
assertions: TestAssertion[];
/** Setup commands to run before test */
setup?: string[];
/** Cleanup commands to run after test */
cleanup?: string[];
/** Skip this test */
skip?: boolean;
/** Only run this test */
only?: boolean;
/** Tags for filtering */
tags?: string[];
}
/**
* Test suite for a skill
*/
export interface SkillTestSuite {
/** Skill name */
skillName: string;
/** Test cases */
tests: SkillTestCase[];
/** Global setup commands */
globalSetup?: string[];
/** Global cleanup commands */
globalCleanup?: string[];
/** Default timeout for all tests */
defaultTimeout?: number;
}
/**
* Individual assertion result
*/
export interface AssertionResult {
/** Assertion that was run */
assertion: TestAssertion;
/** Whether assertion passed */
passed: boolean;
/** Actual value found */
actual?: string;
/** Expected value */
expected?: string;
/** Error message if failed */
error?: string;
/** Duration in milliseconds */
duration: number;
}
/**
* Test case result
*/
export interface TestCaseResult {
/** Test case that was run */
testCase: SkillTestCase;
/** Whether all assertions passed */
passed: boolean;
/** Individual assertion results */
assertions: AssertionResult[];
/** Setup error if any */
setupError?: string;
/** Cleanup error if any */
cleanupError?: string;
/** Total duration in milliseconds */
duration: number;
/** Whether test was skipped */
skipped: boolean;
}
/**
* Test suite result
*/
export interface TestSuiteResult {
/** Skill name */
skillName: string;
/** Whether all tests passed */
passed: boolean;
/** Individual test results */
tests: TestCaseResult[];
/** Number of tests passed */
passedCount: number;
/** Number of tests failed */
failedCount: number;
/** Number of tests skipped */
skippedCount: number;
/** Total duration in milliseconds */
duration: number;
/** Global setup error if any */
globalSetupError?: string;
/** Global cleanup error if any */
globalCleanupError?: string;
}
/**
* Test runner options
*/
export interface TestRunnerOptions {
/** Working directory */
cwd?: string;
/** Default timeout in milliseconds */
timeout?: number;
/** Only run tests with these tags */
tags?: string[];
/** Skip tests with these tags */
skipTags?: string[];
/** Verbose output */
verbose?: boolean;
/** Stop on first failure */
bail?: boolean;
/** Run tests in parallel */
parallel?: boolean;
/** Progress callback */
onProgress?: (event: TestProgressEvent) => void;
}
/**
* Test progress event
*/
export interface TestProgressEvent {
type: 'suite_start' | 'suite_end' | 'test_start' | 'test_end' | 'assertion_start' | 'assertion_end';
skillName?: string;
testName?: string;
assertionType?: TestAssertionType;
passed?: boolean;
error?: string;
}
+3
View File
@@ -75,6 +75,9 @@ export const SkillkitConfig = z.object({
enabledSkills: z.array(z.string()).optional(),
disabledSkills: z.array(z.string()).optional(),
autoSync: z.boolean().default(true),
cacheDir: z.string().optional(),
marketplaceSources: z.array(z.string()).optional(),
defaultTimeout: z.number().optional(),
});
export type SkillkitConfig = z.infer<typeof SkillkitConfig>;
+20
View File
@@ -0,0 +1,20 @@
/**
* Workflow Module
*
* Provides skill composition and workflow orchestration.
*/
export * from './types.js';
export * from './parser.js';
export * from './orchestrator.js';
export { WorkflowOrchestrator, createWorkflowOrchestrator } from './orchestrator.js';
export {
parseWorkflow,
loadWorkflow,
loadWorkflowByName,
listWorkflows,
saveWorkflow,
serializeWorkflow,
validateWorkflow,
createWorkflowTemplate,
} from './parser.js';
+312
View File
@@ -0,0 +1,312 @@
/**
* Workflow Orchestrator
*
* Executes workflows with wave-based orchestration.
*/
import { randomUUID } from 'node:crypto';
import type {
Workflow,
WorkflowWave,
WorkflowSkill,
WorkflowExecution,
WorkflowExecutionStatus,
} from './types.js';
/**
* Skill executor function type
*/
export type SkillExecutor = (
skillName: string,
config?: Record<string, unknown>
) => Promise<{ success: boolean; error?: string }>;
/**
* Progress callback for workflow execution
*/
export type WorkflowProgressCallback = (event: {
type: 'wave_start' | 'wave_complete' | 'skill_start' | 'skill_complete' | 'workflow_complete';
waveIndex?: number;
waveName?: string;
skillName?: string;
status?: WorkflowExecutionStatus;
error?: string;
}) => void;
/**
* Workflow Orchestrator
*
* Manages the execution of workflows with parallel/sequential waves.
*/
export class WorkflowOrchestrator {
private execution: WorkflowExecution | null = null;
private executor: SkillExecutor;
private onProgress?: WorkflowProgressCallback;
constructor(executor: SkillExecutor, onProgress?: WorkflowProgressCallback) {
this.executor = executor;
this.onProgress = onProgress;
}
/**
* Get current execution state
*/
getExecution(): WorkflowExecution | null {
return this.execution;
}
/**
* Execute a workflow
*/
async execute(workflow: Workflow): Promise<WorkflowExecution> {
// Initialize execution state
this.execution = {
workflow,
executionId: randomUUID(),
status: 'running',
currentWave: 0,
waves: workflow.waves.map((wave, index) => ({
waveIndex: index,
waveName: wave.name,
status: 'pending',
skills: wave.skills.map((s) => ({
skill: typeof s === 'string' ? s : s.skill,
status: 'pending' as WorkflowExecutionStatus,
})),
})),
startedAt: new Date().toISOString(),
};
try {
// Execute each wave
for (let i = 0; i < workflow.waves.length; i++) {
if (this.execution.status === 'cancelled' || this.execution.status === 'paused') {
break;
}
this.execution.currentWave = i;
await this.executeWave(workflow.waves[i], i);
// Check if wave failed and should stop
const waveStatus = this.execution.waves[i];
if (waveStatus.status === 'failed' && !workflow.waves[i].continueOnError) {
this.execution.status = 'failed';
this.execution.error = `Wave ${i + 1} failed`;
break;
}
}
// Mark as completed if not already failed/cancelled/paused
if (this.execution.status === 'running') {
this.execution.status = 'completed';
}
this.execution.completedAt = new Date().toISOString();
this.onProgress?.({
type: 'workflow_complete',
status: this.execution.status,
error: this.execution.error,
});
return this.execution;
} catch (error) {
this.execution.status = 'failed';
this.execution.error = error instanceof Error ? error.message : String(error);
this.execution.completedAt = new Date().toISOString();
return this.execution;
}
}
/**
* Execute a single wave
*/
private async executeWave(wave: WorkflowWave, waveIndex: number): Promise<void> {
const waveStatus = this.execution!.waves[waveIndex];
waveStatus.status = 'running';
waveStatus.startedAt = new Date().toISOString();
this.onProgress?.({
type: 'wave_start',
waveIndex,
waveName: wave.name,
});
const skills = wave.skills.map((s) => ({
name: typeof s === 'string' ? s : s.skill,
config: typeof s === 'string' ? undefined : (s as WorkflowSkill).config,
}));
if (wave.parallel) {
// Execute skills in parallel
await Promise.all(
skills.map((skill, skillIndex) =>
this.executeSkill(skill.name, skill.config, waveIndex, skillIndex)
)
);
} else {
// Execute skills sequentially
for (let i = 0; i < skills.length; i++) {
if (this.execution!.status === 'cancelled' || this.execution!.status === 'paused') {
break;
}
await this.executeSkill(skills[i].name, skills[i].config, waveIndex, i);
// Stop on first failure in sequential mode
const skillStatus = waveStatus.skills[i];
if (skillStatus.status === 'failed' && !wave.continueOnError) {
break;
}
}
}
// Determine wave status based on skill statuses
const hasFailures = waveStatus.skills.some((s) => s.status === 'failed');
const allCompleted = waveStatus.skills.every(
(s) => s.status === 'completed' || s.status === 'failed'
);
if (allCompleted) {
waveStatus.status = hasFailures ? 'failed' : 'completed';
}
waveStatus.completedAt = new Date().toISOString();
this.onProgress?.({
type: 'wave_complete',
waveIndex,
waveName: wave.name,
status: waveStatus.status,
});
}
/**
* Execute a single skill
*/
private async executeSkill(
skillName: string,
config: Record<string, unknown> | undefined,
waveIndex: number,
skillIndex: number
): Promise<void> {
const skillStatus = this.execution!.waves[waveIndex].skills[skillIndex];
skillStatus.status = 'running';
skillStatus.startedAt = new Date().toISOString();
this.onProgress?.({
type: 'skill_start',
waveIndex,
skillName,
});
try {
const result = await this.executor(skillName, config);
if (result.success) {
skillStatus.status = 'completed';
} else {
skillStatus.status = 'failed';
skillStatus.error = result.error;
}
} catch (error) {
skillStatus.status = 'failed';
skillStatus.error = error instanceof Error ? error.message : String(error);
}
skillStatus.completedAt = new Date().toISOString();
this.onProgress?.({
type: 'skill_complete',
waveIndex,
skillName,
status: skillStatus.status,
error: skillStatus.error,
});
}
/**
* Pause execution
*/
pause(): boolean {
if (!this.execution || this.execution.status !== 'running') {
return false;
}
this.execution.status = 'paused';
return true;
}
/**
* Check if execution should continue
*/
private shouldContinue(): boolean {
if (!this.execution) return false;
return this.execution.status === 'running';
}
/**
* Resume execution
*/
async resume(): Promise<WorkflowExecution | null> {
if (!this.execution || this.execution.status !== 'paused') {
return null;
}
this.execution.status = 'running';
// Continue from current wave
const workflow = this.execution.workflow;
for (let i = this.execution.currentWave; i < workflow.waves.length; i++) {
if (!this.shouldContinue()) {
break;
}
this.execution.currentWave = i;
// Skip already completed waves
if (this.execution.waves[i].status === 'completed') {
continue;
}
await this.executeWave(workflow.waves[i], i);
const waveStatus = this.execution.waves[i];
if (waveStatus.status === 'failed' && !workflow.waves[i].continueOnError) {
this.execution.status = 'failed';
this.execution.error = `Wave ${i + 1} failed`;
break;
}
}
if (this.execution.status === 'running') {
this.execution.status = 'completed';
}
this.execution.completedAt = new Date().toISOString();
return this.execution;
}
/**
* Cancel execution
*/
cancel(): boolean {
if (!this.execution || this.execution.status === 'completed' || this.execution.status === 'failed') {
return false;
}
this.execution.status = 'cancelled';
this.execution.completedAt = new Date().toISOString();
return true;
}
}
/**
* Create a new workflow orchestrator
*/
export function createWorkflowOrchestrator(
executor: SkillExecutor,
onProgress?: WorkflowProgressCallback
): WorkflowOrchestrator {
return new WorkflowOrchestrator(executor, onProgress);
}
+226
View File
@@ -0,0 +1,226 @@
/**
* Workflow Parser
*
* Parses workflow YAML files into Workflow objects.
*/
import { existsSync, readFileSync, readdirSync, writeFileSync, mkdirSync } from 'node:fs';
import { join } from 'node:path';
import { parse, stringify } from 'yaml';
import type { Workflow, WorkflowWave, WorkflowSkill } from './types.js';
import { WORKFLOWS_DIR, WORKFLOW_EXTENSION } from './types.js';
/**
* Parse a workflow from YAML content
*/
export function parseWorkflow(content: string): Workflow {
const data = parse(content) as Record<string, unknown>;
if (!data.name || typeof data.name !== 'string') {
throw new Error('Workflow must have a name');
}
if (!data.waves || !Array.isArray(data.waves)) {
throw new Error('Workflow must have waves array');
}
const waves: WorkflowWave[] = data.waves.map((wave: unknown, index: number) => {
if (typeof wave !== 'object' || wave === null) {
throw new Error(`Wave ${index} must be an object`);
}
const waveObj = wave as Record<string, unknown>;
const skills = waveObj.skills;
if (!skills || !Array.isArray(skills)) {
throw new Error(`Wave ${index} must have skills array`);
}
return {
name: waveObj.name as string | undefined,
parallel: waveObj.parallel === true,
skills: skills.map((s: unknown) => {
if (typeof s === 'string') {
return s;
}
if (typeof s === 'object' && s !== null) {
const skillObj = s as Record<string, unknown>;
return {
skill: skillObj.skill as string,
config: skillObj.config as Record<string, unknown> | undefined,
condition: skillObj.condition as string | undefined,
} as WorkflowSkill;
}
throw new Error(`Invalid skill in wave ${index}`);
}),
continueOnError: waveObj.continueOnError === true,
};
});
return {
name: data.name as string,
description: data.description as string | undefined,
version: data.version as string | undefined,
author: data.author as string | undefined,
tags: data.tags as string[] | undefined,
waves,
env: data.env as Record<string, string> | undefined,
preHooks: data.preHooks as string[] | undefined,
postHooks: data.postHooks as string[] | undefined,
};
}
/**
* Load a workflow from a file
*/
export function loadWorkflow(filePath: string): Workflow {
if (!existsSync(filePath)) {
throw new Error(`Workflow file not found: ${filePath}`);
}
const content = readFileSync(filePath, 'utf-8');
return parseWorkflow(content);
}
/**
* Load a workflow by name from the project's workflows directory
*/
export function loadWorkflowByName(projectPath: string, name: string): Workflow | null {
const workflowsDir = join(projectPath, '.skillkit', WORKFLOWS_DIR);
if (!existsSync(workflowsDir)) {
return null;
}
// Try exact name match first
const exactPath = join(workflowsDir, `${name}${WORKFLOW_EXTENSION}`);
if (existsSync(exactPath)) {
return loadWorkflow(exactPath);
}
// Try finding by workflow name property
const files = readdirSync(workflowsDir).filter((f) => f.endsWith(WORKFLOW_EXTENSION));
for (const file of files) {
try {
const workflow = loadWorkflow(join(workflowsDir, file));
if (workflow.name === name) {
return workflow;
}
} catch {
// Skip invalid workflow files
}
}
return null;
}
/**
* List all workflows in a project
*/
export function listWorkflows(projectPath: string): Workflow[] {
const workflowsDir = join(projectPath, '.skillkit', WORKFLOWS_DIR);
if (!existsSync(workflowsDir)) {
return [];
}
const files = readdirSync(workflowsDir).filter((f) => f.endsWith(WORKFLOW_EXTENSION));
const workflows: Workflow[] = [];
for (const file of files) {
try {
const workflow = loadWorkflow(join(workflowsDir, file));
workflows.push(workflow);
} catch {
// Skip invalid workflow files
}
}
return workflows;
}
/**
* Save a workflow to a file
*/
export function saveWorkflow(projectPath: string, workflow: Workflow): string {
const workflowsDir = join(projectPath, '.skillkit', WORKFLOWS_DIR);
if (!existsSync(workflowsDir)) {
mkdirSync(workflowsDir, { recursive: true });
}
const fileName = `${workflow.name.replace(/[^a-z0-9-]/gi, '-').toLowerCase()}${WORKFLOW_EXTENSION}`;
const filePath = join(workflowsDir, fileName);
writeFileSync(filePath, stringify(workflow));
return filePath;
}
/**
* Serialize a workflow to YAML
*/
export function serializeWorkflow(workflow: Workflow): string {
return stringify(workflow);
}
/**
* Validate a workflow
*/
export function validateWorkflow(workflow: Workflow): { valid: boolean; errors: string[] } {
const errors: string[] = [];
if (!workflow.name) {
errors.push('Workflow must have a name');
}
if (!workflow.waves || workflow.waves.length === 0) {
errors.push('Workflow must have at least one wave');
}
for (let i = 0; i < workflow.waves.length; i++) {
const wave = workflow.waves[i];
if (!wave.skills || wave.skills.length === 0) {
errors.push(`Wave ${i + 1} must have at least one skill`);
}
for (let j = 0; j < wave.skills.length; j++) {
const skill = wave.skills[j];
const skillName = typeof skill === 'string' ? skill : skill.skill;
if (!skillName) {
errors.push(`Wave ${i + 1}, skill ${j + 1} must have a name`);
}
}
}
return {
valid: errors.length === 0,
errors,
};
}
/**
* Create a new workflow from a template
*/
export function createWorkflowTemplate(name: string, description?: string): Workflow {
return {
name,
description: description || `Workflow: ${name}`,
version: '1.0.0',
waves: [
{
name: 'Setup',
parallel: true,
skills: [],
},
{
name: 'Main',
parallel: false,
skills: [],
},
],
};
}
+112
View File
@@ -0,0 +1,112 @@
/**
* Workflow Types
*
* Types for skill composition and workflow orchestration.
*/
/**
* A skill reference within a workflow
*/
export interface WorkflowSkill {
/** Skill name or source (e.g., "typescript-strict-mode" or "owner/repo/skill") */
skill: string;
/** Optional configuration overrides */
config?: Record<string, unknown>;
/** Optional condition to run this skill */
condition?: string;
}
/**
* A wave of skills to execute (parallel or sequential)
*/
export interface WorkflowWave {
/** Wave name/description */
name?: string;
/** Whether skills in this wave run in parallel */
parallel: boolean;
/** Skills to execute in this wave */
skills: (string | WorkflowSkill)[];
/** Continue to next wave even if this wave has failures */
continueOnError?: boolean;
}
/**
* Workflow definition
*/
export interface Workflow {
/** Workflow name (used as identifier) */
name: string;
/** Human-readable description */
description?: string;
/** Workflow version */
version?: string;
/** Author information */
author?: string;
/** Tags for discovery */
tags?: string[];
/** Waves of skills to execute */
waves: WorkflowWave[];
/** Environment variables to set */
env?: Record<string, string>;
/** Pre-execution hooks */
preHooks?: string[];
/** Post-execution hooks */
postHooks?: string[];
}
/**
* Workflow execution status
*/
export type WorkflowExecutionStatus = 'pending' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled';
/**
* Status of a wave execution
*/
export interface WaveExecutionStatus {
/** Wave index */
waveIndex: number;
/** Wave name */
waveName?: string;
/** Status */
status: WorkflowExecutionStatus;
/** Skills statuses */
skills: {
skill: string;
status: WorkflowExecutionStatus;
startedAt?: string;
completedAt?: string;
error?: string;
}[];
/** When wave started */
startedAt?: string;
/** When wave completed */
completedAt?: string;
}
/**
* Workflow execution state
*/
export interface WorkflowExecution {
/** Workflow being executed */
workflow: Workflow;
/** Execution ID */
executionId: string;
/** Overall status */
status: WorkflowExecutionStatus;
/** Current wave index */
currentWave: number;
/** Wave statuses */
waves: WaveExecutionStatus[];
/** When execution started */
startedAt: string;
/** When execution completed */
completedAt?: string;
/** Error if failed */
error?: string;
}
/**
* Workflow file location
*/
export const WORKFLOWS_DIR = 'workflows';
export const WORKFLOW_EXTENSION = '.yaml';
+161
View File
@@ -0,0 +1,161 @@
# @skillkit/tui
[![npm version](https://img.shields.io/npm/v/@skillkit/tui.svg)](https://www.npmjs.com/package/@skillkit/tui)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
**Interactive terminal UI for SkillKit** - browse, install, translate, and manage skills visually in your terminal.
## Installation
```bash
npm install @skillkit/tui
# or
npm install -g skillkit # includes TUI
```
## Quick Start
```bash
skillkit ui
# or just
skillkit
```
## Features
- **Browse Skills**: Explore 33+ skill repositories with search and filtering
- **Smart Recommendations**: See project-aware skill suggestions with match scores
- **Cross-Agent Translation**: Convert skills between any of 17 agent formats
- **Context Management**: View detected stack and sync to all agents
- **Multi-Agent Install**: Install skills to multiple agents at once
- **Responsive Design**: Adapts to any terminal size
## Screens
### Home
Overview of your project and quick actions. Shows detected agents, installed skills count, and navigation hints.
### Browse (b)
Explore available skills from curated repositories. Features:
- Search skills with `/`
- Filter by tags
- View skill details
- One-key installation
### Recommend (r)
AI-powered skill suggestions based on your project:
- Analyzes your package.json, configs, and file structure
- Shows match percentage for each skill
- Explains why skills are recommended
- Filter by minimum score
### Translate (t)
Convert skills between agent formats:
- Select source skill
- Choose target agent(s)
- Preview translation
- Apply with confirmation
### Context (c)
View and manage project context:
- Detected languages and frameworks
- Found testing tools and databases
- Installed agents
- Sync context to all agents
### Installed (l)
Manage your installed skills:
- View all installed skills
- Enable/disable skills
- Remove skills
- Update from source
### Sync (s)
Sync skills across agents:
- Select target agents
- Preview changes
- Apply sync
### Settings (,)
Configure SkillKit:
- Default agent
- Auto-sync settings
- Skill directories
## Keyboard Shortcuts
| Key | Action |
|-----|--------|
| `h` | Home screen |
| `b` | Browse skills |
| `r` | Recommendations |
| `t` | Translate skills |
| `c` | Context management |
| `l` | List installed |
| `s` | Sync skills |
| `,` | Settings |
| `↑/↓` | Navigate lists |
| `Enter` | Select / Confirm |
| `/` | Search |
| `m` | Multi-select mode |
| `Tab` | Switch focus |
| `Esc` | Go back |
| `?` | Help |
| `q` | Quit |
## Programmatic Usage
```typescript
import { startTUI, TUIOptions } from '@skillkit/tui';
// Launch with defaults
await startTUI();
// Launch with options
await startTUI({
projectPath: './my-project',
initialScreen: 'browse',
theme: 'dark',
});
```
## Architecture
Built with:
- **Ink** - React for CLIs
- **React** - Component architecture
- **@skillkit/core** - Core functionality
```
src/
├── app.tsx # Main app component
├── screens/ # Screen components
│ ├── Home.tsx
│ ├── Browse.tsx
│ ├── Recommend.tsx
│ ├── Translate.tsx
│ ├── Context.tsx
│ └── ...
├── components/ # Reusable UI components
│ ├── SkillCard.tsx
│ ├── AgentSelector.tsx
│ └── ...
└── hooks/ # React hooks
├── useSkills.ts
├── useContext.ts
└── ...
```
## Terminal Requirements
- Minimum: 80x24 characters
- Recommended: 120x40 characters
- Supports: True Color, 256 colors, basic ANSI
## Documentation
Full documentation: https://github.com/rohitg00/skillkit
## License
Apache-2.0
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/tui",
"version": "1.3.0",
"version": "1.4.0",
"description": "Terminal UI for SkillKit",
"type": "module",
"main": "./dist/index.js",
+38 -10
View File
@@ -9,8 +9,15 @@ import { Settings } from './screens/Settings.js';
import { Recommend } from './screens/Recommend.js';
import { Translate } from './screens/Translate.js';
import { Context } from './screens/Context.js';
import { Workflow } from './screens/Workflow.js';
import { Execute } from './screens/Execute.js';
import { History } from './screens/History.js';
import { Marketplace } from './screens/Marketplace.js';
import { Memory } from './screens/Memory.js';
import { Team } from './screens/Team.js';
import { Plugins } from './screens/Plugins.js';
export type Screen = 'home' | 'browse' | 'installed' | 'sync' | 'settings' | 'recommend' | 'translate' | 'context';
export type Screen = 'home' | 'browse' | 'installed' | 'sync' | 'settings' | 'recommend' | 'translate' | 'context' | 'workflow' | 'execute' | 'history' | 'marketplace' | 'memory' | 'team' | 'plugins';
export function App() {
const [screen, setScreen] = useState<Screen>('home');
@@ -21,6 +28,24 @@ export function App() {
const rows = stdout?.rows || 24;
const showSidebar = cols >= 70;
const NAV_KEYS: Record<string, Screen> = {
h: 'home',
m: 'marketplace',
b: 'browse',
w: 'workflow',
x: 'execute',
y: 'history',
r: 'recommend',
t: 'translate',
c: 'context',
e: 'memory',
i: 'installed',
s: 'sync',
a: 'team',
p: 'plugins',
',': 'settings',
};
useInput((input, key) => {
if (input === 'q') {
exit();
@@ -30,14 +55,10 @@ export function App() {
setScreen('home');
return;
}
if (input === 'h') setScreen('home');
if (input === 'b') setScreen('browse');
if (input === 'l') setScreen('installed');
if (input === 's') setScreen('sync');
if (input === ',') setScreen('settings');
if (input === 'r') setScreen('recommend');
if (input === 't') setScreen('translate');
if (input === 'c') setScreen('context');
const targetScreen = NAV_KEYS[input];
if (targetScreen) {
setScreen(targetScreen);
}
});
const renderScreen = () => {
@@ -50,6 +71,13 @@ export function App() {
case 'recommend': return <Recommend cols={cols} rows={rows} />;
case 'translate': return <Translate cols={cols} rows={rows} />;
case 'context': return <Context cols={cols} rows={rows} />;
case 'workflow': return <Workflow cols={cols} rows={rows} />;
case 'execute': return <Execute cols={cols} rows={rows} />;
case 'history': return <History cols={cols} rows={rows} />;
case 'marketplace': return <Marketplace cols={cols} rows={rows} />;
case 'memory': return <Memory cols={cols} rows={rows} />;
case 'team': return <Team cols={cols} rows={rows} />;
case 'plugins': return <Plugins cols={cols} rows={rows} />;
}
};
@@ -64,7 +92,7 @@ export function App() {
</Box>
</Box>
<Box>
<Text dimColor>h Home b Browse r Rec t Trans c Ctx l List s Sync , Config q Quit</Text>
<Text dimColor>h Home m Market b Browse i Inst w Wflow x Exec a Team p Plug r Rec t Trans c Ctx e Mem s Sync , Cfg q Quit</Text>
</Box>
</Box>
);
+44 -11
View File
@@ -8,15 +8,27 @@ interface SidebarProps {
isCompact?: boolean;
}
const NAV: { id: Screen; label: string }[] = [
{ id: 'home', label: 'Home' },
{ id: 'browse', label: 'Browse' },
{ id: 'recommend', label: 'Recommend' },
{ id: 'translate', label: 'Translate' },
{ id: 'context', label: 'Context' },
{ id: 'installed', label: 'List' },
{ id: 'sync', label: 'Sync' },
{ id: 'settings', label: 'Config' },
const NAV: { id: Screen; label: string; key: string }[] = [
// Discovery
{ id: 'home', label: 'Home', key: 'h' },
{ id: 'marketplace', label: 'Marketplace', key: 'm' },
{ id: 'browse', label: 'Browse', key: 'b' },
// Execution
{ id: 'workflow', label: 'Workflows', key: 'w' },
{ id: 'execute', label: 'Execute', key: 'x' },
{ id: 'history', label: 'History', key: 'y' },
// Collaboration
{ id: 'team', label: 'Team', key: 'a' },
{ id: 'plugins', label: 'Plugins', key: 'p' },
// Tools
{ id: 'recommend', label: 'Recommend', key: 'r' },
{ id: 'translate', label: 'Translate', key: 't' },
{ id: 'context', label: 'Context', key: 'c' },
{ id: 'memory', label: 'Memory', key: 'e' },
// Management
{ id: 'installed', label: 'Installed', key: 'i' },
{ id: 'sync', label: 'Sync', key: 's' },
{ id: 'settings', label: 'Config', key: ',' },
];
export function Sidebar({ screen }: SidebarProps) {
@@ -24,6 +36,7 @@ export function Sidebar({ screen }: SidebarProps) {
<Box flexDirection="column" width={14} borderStyle="single" paddingX={1}>
<Text bold color={colors.primary}>SkillKit</Text>
{/* Discovery (0-2) */}
{NAV.slice(0, 3).map((item) => (
<Text key={item.id} inverse={screen === item.id}>
{screen === item.id ? symbols.bullet : ' '}{item.label}
@@ -32,7 +45,8 @@ export function Sidebar({ screen }: SidebarProps) {
<Text> </Text>
{NAV.slice(3, 5).map((item) => (
{/* Execution (3-5) */}
{NAV.slice(3, 6).map((item) => (
<Text key={item.id} inverse={screen === item.id}>
{screen === item.id ? symbols.bullet : ' '}{item.label}
</Text>
@@ -40,7 +54,26 @@ export function Sidebar({ screen }: SidebarProps) {
<Text> </Text>
{NAV.slice(5).map((item) => (
{/* Collaboration (6-7) */}
{NAV.slice(6, 8).map((item) => (
<Text key={item.id} inverse={screen === item.id}>
{screen === item.id ? symbols.bullet : ' '}{item.label}
</Text>
))}
<Text> </Text>
{/* Tools (8-11) */}
{NAV.slice(8, 12).map((item) => (
<Text key={item.id} inverse={screen === item.id}>
{screen === item.id ? symbols.bullet : ' '}{item.label}
</Text>
))}
<Text> </Text>
{/* Management (12-14) */}
{NAV.slice(12).map((item) => (
<Text key={item.id} inverse={screen === item.id}>
{screen === item.id ? symbols.bullet : ' '}{item.label}
</Text>
+1
View File
@@ -2,3 +2,4 @@ export { useSkills } from './useSkills.js';
export { useMarketplace } from './useMarketplace.js';
export { useKeyboard, useListNavigation } from './useKeyboard.js';
export { useRecommend } from './useRecommend.js';
export { useMemory } from './useMemory.js';
+81 -10
View File
@@ -1,5 +1,7 @@
import { useState, useCallback, useEffect } from 'react';
import { detectProvider } from '@skillkit/core';
import { detectProvider, loadConfig, extractFrontmatter } from '@skillkit/core';
import { readFileSync, existsSync } from 'node:fs';
import { join } from 'node:path';
import type { SkillItem } from '../components/SkillList.js';
export interface RepoInfo {
@@ -7,7 +9,8 @@ export interface RepoInfo {
name: string;
}
const POPULAR_REPOS: RepoInfo[] = [
// Default popular repos - can be extended via config.marketplaceSources
const DEFAULT_REPOS: RepoInfo[] = [
{ source: 'anthropics/skills', name: 'Anthropic Official' },
{ source: 'vercel-labs/agent-skills', name: 'Vercel Labs' },
{ source: 'expo/skills', name: 'Expo / React Native' },
@@ -40,6 +43,53 @@ const POPULAR_REPOS: RepoInfo[] = [
{ source: 'intellectronica/agent-skills', name: 'Context7' },
];
/**
* Get marketplace repos from config or use defaults
*/
function getMarketplaceRepos(): RepoInfo[] {
try {
const config = loadConfig();
if (config.marketplaceSources?.length) {
// Merge config sources with defaults, config takes priority
const configRepos: RepoInfo[] = config.marketplaceSources.map(source => ({
source,
name: source.split('/').pop() || source,
}));
// Add defaults that aren't in config
const existingSources = new Set(configRepos.map(r => r.source));
for (const repo of DEFAULT_REPOS) {
if (!existingSources.has(repo.source)) {
configRepos.push(repo);
}
}
return configRepos;
}
} catch {
// Config load failed, use defaults
}
return DEFAULT_REPOS;
}
/**
* Try to read skill description from frontmatter
*/
function readSkillDescription(skillPath: string): string | undefined {
const skillMdPath = join(skillPath, 'SKILL.md');
if (!existsSync(skillMdPath)) {
return undefined;
}
try {
const content = readFileSync(skillMdPath, 'utf-8');
const frontmatter = extractFrontmatter(content);
if (frontmatter && typeof frontmatter.description === 'string') {
return frontmatter.description;
}
} catch {
// Failed to read, return undefined
}
return undefined;
}
interface FetchedSkill {
name: string;
source: string;
@@ -54,6 +104,7 @@ interface UseMarketplaceResult {
totalCount: number;
repos: RepoInfo[];
currentRepo: string | null;
failedRepos: string[];
refresh: () => void;
search: (query: string) => void;
fetchRepo: (source: string) => Promise<void>;
@@ -67,6 +118,8 @@ export function useMarketplace(): UseMarketplaceResult {
const [error, setError] = useState<string | null>(null);
const [currentRepo, setCurrentRepo] = useState<string | null>(null);
const [fetchedRepos, setFetchedRepos] = useState<Set<string>>(new Set());
const [failedRepos, setFailedRepos] = useState<string[]>([]);
const [repos] = useState<RepoInfo[]>(() => getMarketplaceRepos());
const fetchRepo = useCallback(async (source: string) => {
if (fetchedRepos.has(source)) return;
@@ -87,12 +140,13 @@ export function useMarketplace(): UseMarketplaceResult {
throw new Error(result.error || 'Failed to fetch skills');
}
const repoName = POPULAR_REPOS.find(r => r.source === source)?.name || source;
const repoName = repos.find(r => r.source === source)?.name || source;
const newSkills: FetchedSkill[] = result.discoveredSkills.map(skill => ({
name: skill.name,
source: source,
repoName: repoName,
description: undefined,
// Try to read description from skill frontmatter
description: readSkillDescription(skill.path),
}));
setAllSkills(prev => {
@@ -107,30 +161,44 @@ export function useMarketplace(): UseMarketplaceResult {
rmSync(result.tempRoot, { recursive: true, force: true });
}
} catch (err) {
setError(err instanceof Error ? err.message : 'Failed to fetch repository');
const errorMsg = err instanceof Error ? err.message : 'Failed to fetch repository';
setError(errorMsg);
// Track failed repos for display
setFailedRepos(prev => prev.includes(source) ? prev : [...prev, source]);
} finally {
setLoading(false);
setCurrentRepo(null);
}
}, [fetchedRepos]);
}, [fetchedRepos, repos]);
const fetchAllRepos = useCallback(async () => {
setLoading(true);
setError(null);
const failures: string[] = [];
for (const repo of POPULAR_REPOS) {
for (const repo of repos) {
if (!fetchedRepos.has(repo.source)) {
setCurrentRepo(repo.source);
try {
await fetchRepo(repo.source);
} catch {
} catch (err) {
// Track which repos failed
failures.push(repo.source);
}
}
}
// Update failed repos list
if (failures.length > 0) {
setFailedRepos(prev => {
const combined = [...prev, ...failures];
return [...new Set(combined)]; // deduplicate
});
}
setLoading(false);
setCurrentRepo(null);
}, [fetchRepo, fetchedRepos]);
}, [fetchRepo, fetchedRepos, repos]);
const search = useCallback((query: string) => {
if (!query.trim()) {
@@ -153,6 +221,8 @@ export function useMarketplace(): UseMarketplaceResult {
setFetchedRepos(new Set());
setAllSkills([]);
setFilteredSkills([]);
setFailedRepos([]);
setError(null);
}, []);
useEffect(() => {
@@ -170,8 +240,9 @@ export function useMarketplace(): UseMarketplaceResult {
loading,
error,
totalCount: allSkills.length,
repos: POPULAR_REPOS,
repos,
currentRepo,
failedRepos,
refresh,
search,
fetchRepo,
+141
View File
@@ -0,0 +1,141 @@
import { useState, useEffect, useCallback } from 'react';
import {
LearningStore,
ObservationStore,
getMemoryStatus,
createMemoryInjector,
type Learning,
type Observation,
type MemoryStatus,
} from '@skillkit/core';
interface UseMemoryResult {
learnings: Learning[];
observations: Observation[];
status: MemoryStatus | null;
loading: boolean;
error: string | null;
isGlobal: boolean;
setIsGlobal: (isGlobal: boolean) => void;
refresh: () => void;
search: (query: string) => Learning[];
deleteLearning: (id: string) => boolean;
deleteObservation: (id: string) => boolean;
}
export function useMemory(): UseMemoryResult {
const [learnings, setLearnings] = useState<Learning[]>([]);
const [observations, setObservations] = useState<Observation[]>([]);
const [status, setStatus] = useState<MemoryStatus | null>(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
const [isGlobal, setIsGlobal] = useState(false);
const projectPath = process.cwd();
const refresh = useCallback(() => {
setLoading(true);
setError(null);
try {
// Get memory status
const memStatus = getMemoryStatus(projectPath);
setStatus(memStatus);
// Load learnings
const learningStore = new LearningStore(
isGlobal ? 'global' : 'project',
isGlobal ? undefined : projectPath
);
setLearnings(learningStore.getAll());
// Load observations (project only)
if (memStatus.hasObservations) {
const obsStore = new ObservationStore(projectPath);
setObservations(obsStore.getAll());
} else {
setObservations([]);
}
} catch (err) {
setError(err instanceof Error ? err.message : 'Failed to load memory');
setLearnings([]);
setObservations([]);
} finally {
setLoading(false);
}
}, [projectPath, isGlobal]);
const search = useCallback(
(query: string): Learning[] => {
if (!query.trim()) {
return [];
}
try {
const injector = createMemoryInjector(projectPath);
const results = injector.search(query, {
includeGlobal: true,
maxLearnings: 50,
minRelevance: 0,
});
return results.map((r) => r.learning);
} catch {
return [];
}
},
[projectPath]
);
const deleteLearning = useCallback(
(id: string): boolean => {
try {
const store = new LearningStore(
isGlobal ? 'global' : 'project',
isGlobal ? undefined : projectPath
);
const result = store.delete(id);
if (result) {
refresh();
}
return result;
} catch {
return false;
}
},
[projectPath, isGlobal, refresh]
);
const deleteObservation = useCallback(
(id: string): boolean => {
try {
const store = new ObservationStore(projectPath);
const result = store.delete(id);
if (result) {
refresh();
}
return result;
} catch {
return false;
}
},
[projectPath, refresh]
);
useEffect(() => {
refresh();
}, [refresh]);
return {
learnings,
observations,
status,
loading,
error,
isGlobal,
setIsGlobal,
refresh,
search,
deleteLearning,
deleteObservation,
};
}
+32 -219
View File
@@ -4,14 +4,12 @@ import {
ContextManager,
type ScoredSkill,
type ProjectProfile,
type SkillIndex,
type SkillSummary,
loadIndex as loadIndexFromCache,
saveIndex,
buildSkillIndex,
isIndexStale,
KNOWN_SKILL_REPOS,
} from '@skillkit/core';
import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { join } from 'node:path';
const INDEX_PATH = join(process.env.HOME || '~', '.skillkit', 'index.json');
const INDEX_CACHE_HOURS = 24;
interface UseRecommendResult {
recommendations: ScoredSkill[];
@@ -26,164 +24,6 @@ interface UseRecommendResult {
searchResults: ScoredSkill[];
}
/**
* Sample skills for the index (matches CLI implementation)
*/
function getSampleSkills(): SkillSummary[] {
return [
{
name: 'vercel-react-best-practices',
description: 'Modern React patterns including Server Components, hooks best practices, and performance optimization',
source: 'vercel-labs/agent-skills',
tags: ['react', 'frontend', 'typescript', 'nextjs', 'performance'],
compatibility: {
frameworks: ['react', 'nextjs'],
languages: ['typescript', 'javascript'],
libraries: [],
},
popularity: 1500,
quality: 95,
lastUpdated: new Date().toISOString(),
verified: true,
},
{
name: 'tailwind-v4-patterns',
description: 'Tailwind CSS v4 utility patterns, responsive design, and component styling best practices',
source: 'vercel-labs/agent-skills',
tags: ['tailwind', 'css', 'styling', 'frontend', 'responsive'],
compatibility: {
frameworks: [],
languages: ['typescript', 'javascript'],
libraries: ['tailwindcss'],
},
popularity: 1200,
quality: 92,
lastUpdated: new Date().toISOString(),
verified: true,
},
{
name: 'nextjs-app-router',
description: 'Next.js App Router patterns including layouts, server actions, and data fetching',
source: 'vercel-labs/agent-skills',
tags: ['nextjs', 'react', 'routing', 'server-actions', 'frontend'],
compatibility: {
frameworks: ['nextjs'],
languages: ['typescript', 'javascript'],
libraries: [],
},
popularity: 1100,
quality: 94,
lastUpdated: new Date().toISOString(),
verified: true,
},
{
name: 'typescript-strict-patterns',
description: 'TypeScript strict mode patterns, type safety, and advanced type utilities',
source: 'anthropics/skills',
tags: ['typescript', 'types', 'safety', 'patterns'],
compatibility: {
frameworks: [],
languages: ['typescript'],
libraries: [],
},
popularity: 900,
quality: 90,
lastUpdated: new Date().toISOString(),
verified: true,
},
{
name: 'supabase-best-practices',
description: 'Supabase integration patterns including auth, database queries, and real-time subscriptions',
source: 'anthropics/skills',
tags: ['supabase', 'database', 'auth', 'backend', 'postgresql'],
compatibility: {
frameworks: [],
languages: ['typescript', 'javascript'],
libraries: ['@supabase/supabase-js'],
},
popularity: 800,
quality: 88,
lastUpdated: new Date().toISOString(),
verified: true,
},
{
name: 'vitest-testing-patterns',
description: 'Testing patterns with Vitest including mocking, assertions, and test organization',
source: 'anthropics/skills',
tags: ['vitest', 'testing', 'typescript', 'mocking', 'tdd'],
compatibility: {
frameworks: [],
languages: ['typescript', 'javascript'],
libraries: ['vitest'],
},
popularity: 700,
quality: 86,
lastUpdated: new Date().toISOString(),
verified: false,
},
{
name: 'prisma-database-patterns',
description: 'Prisma ORM patterns for schema design, migrations, and efficient queries',
source: 'vercel-labs/agent-skills',
tags: ['prisma', 'database', 'orm', 'postgresql', 'backend'],
compatibility: {
frameworks: [],
languages: ['typescript'],
libraries: ['@prisma/client'],
},
popularity: 850,
quality: 89,
lastUpdated: new Date().toISOString(),
verified: true,
},
{
name: 'security-best-practices',
description: 'Security patterns for web applications including XSS prevention, CSRF, and secure headers',
source: 'trailofbits/skills',
tags: ['security', 'xss', 'csrf', 'headers', 'owasp'],
compatibility: {
frameworks: [],
languages: ['typescript', 'javascript', 'python'],
libraries: [],
},
popularity: 600,
quality: 95,
lastUpdated: new Date().toISOString(),
verified: true,
},
{
name: 'python-fastapi-patterns',
description: 'FastAPI best practices for building high-performance Python APIs',
source: 'python-skills/fastapi',
tags: ['python', 'fastapi', 'backend', 'api', 'async'],
compatibility: {
frameworks: ['fastapi'],
languages: ['python'],
libraries: [],
},
popularity: 550,
quality: 85,
lastUpdated: new Date().toISOString(),
verified: false,
},
{
name: 'zustand-state-management',
description: 'Zustand state management patterns for React applications',
source: 'react-skills/state',
tags: ['zustand', 'react', 'state-management', 'frontend'],
compatibility: {
frameworks: ['react'],
languages: ['typescript', 'javascript'],
libraries: ['zustand'],
},
popularity: 650,
quality: 84,
lastUpdated: new Date().toISOString(),
verified: false,
},
];
}
export function useRecommend(projectPath: string = process.cwd()): UseRecommendResult {
const [recommendations, setRecommendations] = useState<ScoredSkill[]>([]);
const [searchResults, setSearchResults] = useState<ScoredSkill[]>([]);
@@ -194,31 +34,22 @@ export function useRecommend(projectPath: string = process.cwd()): UseRecommendR
const [indexStatus, setIndexStatus] = useState<'missing' | 'stale' | 'fresh'>('missing');
const [engine] = useState(() => new RecommendationEngine());
const loadIndex = useCallback((): SkillIndex | null => {
if (!existsSync(INDEX_PATH)) {
const loadIndex = useCallback(() => {
const index = loadIndexFromCache();
if (!index) {
setIndexStatus('missing');
return null;
}
try {
const content = readFileSync(INDEX_PATH, 'utf-8');
const index = JSON.parse(content) as SkillIndex;
// Check if index is stale
const lastUpdated = new Date(index.lastUpdated);
const hoursSinceUpdate = (Date.now() - lastUpdated.getTime()) / (1000 * 60 * 60);
if (hoursSinceUpdate > INDEX_CACHE_HOURS) {
setIndexStatus('stale');
} else {
setIndexStatus('fresh');
}
return index;
} catch {
setIndexStatus('missing');
return null;
// Check if index is stale
if (isIndexStale(index)) {
setIndexStatus('stale');
} else {
setIndexStatus('fresh');
}
return index;
}, []);
const getProjectProfile = useCallback((): ProjectProfile | null => {
@@ -293,42 +124,24 @@ export function useRecommend(projectPath: string = process.cwd()): UseRecommendR
setLoading(true);
setError(null);
try {
const sampleIndex: SkillIndex = {
version: 1,
lastUpdated: new Date().toISOString(),
skills: getSampleSkills(),
sources: [
{
name: 'vercel-labs',
url: 'https://github.com/vercel-labs/agent-skills',
lastFetched: new Date().toISOString(),
skillCount: 5,
},
{
name: 'anthropics',
url: 'https://github.com/anthropics/skills',
lastFetched: new Date().toISOString(),
skillCount: 3,
},
],
};
// Fetch skills from known GitHub repositories
buildSkillIndex(KNOWN_SKILL_REPOS)
.then(({ index, errors }) => {
if (errors.length > 0) {
console.warn('Index update warnings:', errors);
}
// Save index
const indexDir = join(process.env.HOME || '~', '.skillkit');
if (!existsSync(indexDir)) {
mkdirSync(indexDir, { recursive: true });
}
// Save the fetched index
saveIndex(index);
setIndexStatus('fresh');
writeFileSync(INDEX_PATH, JSON.stringify(sampleIndex, null, 2));
setIndexStatus('fresh');
// Reload recommendations
loadRecommendations();
} catch (err) {
setError(err instanceof Error ? err.message : 'Failed to update index');
setLoading(false);
}
// Reload recommendations with new index
loadRecommendations();
})
.catch((err) => {
setError(err instanceof Error ? err.message : 'Failed to update index');
setLoading(false);
});
}, [loadRecommendations]);
const search = useCallback((query: string) => {
+131
View File
@@ -0,0 +1,131 @@
import { useState, useEffect } from 'react';
import { Box, Text, useInput } from 'ink';
import { colors, symbols } from '../theme.js';
import { createSessionManager, type SessionState, type CurrentExecution } from '@skillkit/core';
interface Props {
cols?: number;
rows?: number;
}
export function Execute({ rows = 24 }: Props) {
const [session, setSession] = useState<SessionState | null>(null);
const [loading, setLoading] = useState(true);
const maxVisible = Math.max(5, rows - 10);
useEffect(() => {
loadSession();
// Poll for updates
const interval = setInterval(loadSession, 1000);
return () => clearInterval(interval);
}, []);
const loadSession = () => {
try {
const manager = createSessionManager(process.cwd());
const state = manager.get();
setSession(state);
} catch {
setSession(null);
}
setLoading(false);
};
useInput((input, _key) => {
if (input === 'r') loadSession();
else if (input === 'p' && session?.currentExecution?.status === 'running') {
const manager = createSessionManager(process.cwd());
manager.pause();
loadSession();
}
else if (input === 'c' && session?.currentExecution?.status === 'paused') {
const manager = createSessionManager(process.cwd());
manager.resume();
loadSession();
}
});
const renderExecution = (exec: CurrentExecution) => {
const completedTasks = exec.tasks.filter(t => t.status === 'completed').length;
const failedTasks = exec.tasks.filter(t => t.status === 'failed').length;
const progress = exec.totalSteps > 0 ? Math.round((completedTasks / exec.totalSteps) * 100) : 0;
const statusColor = exec.status === 'running' ? 'yellow' :
exec.status === 'completed' ? 'green' :
exec.status === 'paused' ? 'blue' :
exec.status === 'failed' ? 'red' : 'white';
const visibleTasks = exec.tasks.slice(0, maxVisible);
return (
<Box flexDirection="column" marginTop={1}>
<Text bold>{exec.skillName}</Text>
<Text>Source: <Text dimColor>{exec.skillSource}</Text></Text>
<Text>Status: <Text color={statusColor}>{exec.status.toUpperCase()}</Text></Text>
<Text>Progress: {completedTasks}/{exec.totalSteps} ({progress}%)</Text>
{/* Progress bar */}
<Box marginY={1}>
<Text>[</Text>
<Text color="green">{'█'.repeat(Math.floor(progress / 5))}</Text>
<Text dimColor>{'░'.repeat(20 - Math.floor(progress / 5))}</Text>
<Text>]</Text>
</Box>
{/* Task list */}
<Text bold>Tasks:</Text>
{visibleTasks.map((task, i) => {
const icon = task.status === 'completed' ? symbols.success :
task.status === 'failed' ? symbols.error :
task.status === 'in_progress' ? symbols.warning :
task.status === 'paused' ? symbols.info :
symbols.bullet;
const color = task.status === 'completed' ? 'green' :
task.status === 'failed' ? 'red' :
task.status === 'in_progress' ? 'yellow' :
task.status === 'paused' ? 'blue' : 'white';
return (
<Text key={task.id || i} color={color}>
{icon} {task.name} {task.error && <Text dimColor>({task.error})</Text>}
</Text>
);
})}
{exec.tasks.length > maxVisible && (
<Text dimColor> ... and {exec.tasks.length - maxVisible} more</Text>
)}
{failedTasks > 0 && (
<Box marginTop={1}>
<Text color="red">{failedTasks} task(s) failed</Text>
</Box>
)}
</Box>
);
};
return (
<Box flexDirection="column">
<Text bold color={colors.primary}>EXECUTION MONITOR</Text>
{loading && <Text>Loading session...</Text>}
{!loading && !session?.currentExecution && (
<Box marginTop={1} flexDirection="column">
<Text dimColor>No active execution.</Text>
<Text dimColor>Run a skill with: skillkit run {'<skill>'}</Text>
</Box>
)}
{!loading && session?.currentExecution && renderExecution(session.currentExecution)}
<Box marginTop={1}>
<Text dimColor>
{session?.currentExecution?.status === 'running' ? 'p=pause ' : ''}
{session?.currentExecution?.status === 'paused' ? 'c=continue ' : ''}
r=refresh q=quit
</Text>
</Box>
</Box>
);
}
+127
View File
@@ -0,0 +1,127 @@
import { useState, useEffect } from 'react';
import { Box, Text, useInput } from 'ink';
import { colors, symbols } from '../theme.js';
import { createSessionManager, type ExecutionHistory } from '@skillkit/core';
interface Props {
cols?: number;
rows?: number;
}
export function History({ rows = 24 }: Props) {
const [history, setHistory] = useState<ExecutionHistory[]>([]);
const [loading, setLoading] = useState(true);
const [sel, setSel] = useState(0);
const [expanded, setExpanded] = useState(false);
const maxVisible = Math.max(5, rows - 8);
const start = Math.max(0, Math.min(sel - Math.floor(maxVisible / 2), history.length - maxVisible));
const visible = history.slice(start, start + maxVisible);
useEffect(() => {
loadHistory();
}, []);
const loadHistory = () => {
setLoading(true);
try {
const manager = createSessionManager(process.cwd());
const h = manager.getHistory(50);
setHistory(h);
} catch {
setHistory([]);
}
setLoading(false);
};
useInput((input, key) => {
if (loading) return;
if (key.upArrow) {
setSel(i => Math.max(0, i - 1));
setExpanded(false);
}
else if (key.downArrow) {
setSel(i => Math.min(history.length - 1, i + 1));
setExpanded(false);
}
else if (input === 'r') loadHistory();
else if (key.return) setExpanded(e => !e);
});
const formatDuration = (ms: number): string => {
if (ms < 1000) return `${ms}ms`;
if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
return `${(ms / 60000).toFixed(1)}m`;
};
const formatDate = (iso: string): string => {
const d = new Date(iso);
const now = new Date();
const diff = now.getTime() - d.getTime();
if (diff < 60000) return 'Just now';
if (diff < 3600000) return `${Math.floor(diff / 60000)}m ago`;
if (diff < 86400000) return `${Math.floor(diff / 3600000)}h ago`;
return d.toLocaleDateString();
};
return (
<Box flexDirection="column">
<Text bold color={colors.primary}>EXECUTION HISTORY</Text>
<Text dimColor>{history.length} execution(s)</Text>
{loading && <Text>Loading history...</Text>}
{!loading && history.length === 0 && (
<Box marginTop={1} flexDirection="column">
<Text dimColor>No execution history.</Text>
<Text dimColor>Run a skill with: skillkit run {'<skill>'}</Text>
</Box>
)}
{!loading && history.length > 0 && (
<Box marginTop={1} flexDirection="column">
{start > 0 && <Text dimColor> ↑ {start} more</Text>}
{visible.map((entry, i) => {
const idx = start + i;
const isSel = idx === sel;
const icon = entry.status === 'completed' ? symbols.success :
entry.status === 'failed' ? symbols.error :
symbols.warning;
const color = entry.status === 'completed' ? 'green' :
entry.status === 'failed' ? 'red' : 'yellow';
return (
<Box key={idx} flexDirection="column">
<Text inverse={isSel}>
{isSel ? symbols.pointer : ' '}<Text color={color}>{icon}</Text> {entry.skillName.padEnd(25)} {formatDate(entry.completedAt).padEnd(12)} {formatDuration(entry.durationMs)}
</Text>
{isSel && expanded && (
<Box flexDirection="column" marginLeft={3}>
<Text dimColor>Source: {entry.skillSource}</Text>
<Text dimColor>Status: {entry.status}</Text>
{entry.commits.length > 0 && (
<Text dimColor>Commits: {entry.commits.join(', ')}</Text>
)}
{entry.filesModified.length > 0 && (
<Text dimColor>Files: {entry.filesModified.length} modified</Text>
)}
{entry.error && (
<Text color="red">Error: {entry.error}</Text>
)}
</Box>
)}
</Box>
);
})}
{start + maxVisible < history.length && <Text dimColor> ↓ {history.length - start - maxVisible} more</Text>}
</Box>
)}
<Box marginTop={1}>
<Text dimColor>Enter=expand r=refresh q=quit</Text>
</Box>
</Box>
);
}
+182
View File
@@ -0,0 +1,182 @@
import { useState, useEffect } from 'react';
import { Box, Text, useInput } from 'ink';
import { colors, symbols } from '../theme.js';
interface MarketplaceSkill {
name: string;
description: string;
source: string;
repo: string;
tags?: string[];
stars?: number;
}
interface Props {
cols?: number;
rows?: number;
}
// Known skill repositories to aggregate from
const SKILL_SOURCES = [
{ owner: 'composioHQ', repo: 'awesome-claude-code-skills', name: 'Composio Curated' },
{ owner: 'anthropics', repo: 'courses', name: 'Anthropic Official' },
];
export function Marketplace({ rows = 24 }: Props) {
const [skills, setSkills] = useState<MarketplaceSkill[]>([]);
const [loading, setLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
const [sel, setSel] = useState(0);
const [search, setSearch] = useState('');
const [installing, setInstalling] = useState<string | null>(null);
const filtered = skills.filter(s =>
s.name.toLowerCase().includes(search.toLowerCase()) ||
s.description.toLowerCase().includes(search.toLowerCase()) ||
s.tags?.some(t => t.toLowerCase().includes(search.toLowerCase()))
);
const maxVisible = Math.max(5, rows - 10);
const start = Math.max(0, Math.min(sel - Math.floor(maxVisible / 2), filtered.length - maxVisible));
const visible = filtered.slice(start, start + maxVisible);
useEffect(() => {
loadMarketplace();
}, []);
const loadMarketplace = async () => {
setLoading(true);
setError(null);
try {
// Aggregate skills from known sources
const allSkills: MarketplaceSkill[] = [];
for (const source of SKILL_SOURCES) {
try {
// Try to fetch skill index from GitHub
const indexUrl = `https://raw.githubusercontent.com/${source.owner}/${source.repo}/main/skills.json`;
const response = await fetch(indexUrl);
if (response.ok) {
const data = await response.json();
if (Array.isArray(data)) {
allSkills.push(...data.map((s: Record<string, unknown>) => ({
name: String(s.name || 'Unknown'),
description: String(s.description || ''),
source: source.name,
repo: `${source.owner}/${source.repo}`,
tags: Array.isArray(s.tags) ? s.tags as string[] : [],
stars: typeof s.stars === 'number' ? s.stars : undefined,
})));
}
} else {
// Fallback: add the repo itself as a skill source
allSkills.push({
name: source.repo,
description: `Skills from ${source.name}`,
source: source.name,
repo: `${source.owner}/${source.repo}`,
});
}
} catch {
// Add repo as fallback
allSkills.push({
name: source.repo,
description: `Skills from ${source.name}`,
source: source.name,
repo: `${source.owner}/${source.repo}`,
});
}
}
// Add some example skills for demo
if (allSkills.length === 0) {
allSkills.push(
{ name: 'typescript-strict', description: 'Enable strict TypeScript mode', source: 'Built-in', repo: 'skillkit/skills', tags: ['typescript', 'config'] },
{ name: 'eslint-setup', description: 'Set up ESLint with recommended rules', source: 'Built-in', repo: 'skillkit/skills', tags: ['eslint', 'linting'] },
{ name: 'prettier-config', description: 'Configure Prettier formatting', source: 'Built-in', repo: 'skillkit/skills', tags: ['prettier', 'formatting'] },
{ name: 'jest-setup', description: 'Set up Jest testing framework', source: 'Built-in', repo: 'skillkit/skills', tags: ['jest', 'testing'] },
{ name: 'nextjs-auth', description: 'Add authentication to Next.js', source: 'Community', repo: 'community/skills', tags: ['nextjs', 'auth'] },
);
}
setSkills(allSkills);
} catch (e) {
setError(e instanceof Error ? e.message : 'Failed to load marketplace');
}
setLoading(false);
};
useInput((input, key) => {
if (loading || installing) return;
if (key.upArrow) setSel(i => Math.max(0, i - 1));
else if (key.downArrow) setSel(i => Math.min(filtered.length - 1, i + 1));
else if (input === 'r') loadMarketplace();
else if (input === '/') setSearch('');
else if (key.backspace || key.delete) setSearch(s => s.slice(0, -1));
else if (key.return && filtered[sel]) {
setInstalling(filtered[sel].name);
// Simulate installation
setTimeout(() => setInstalling(null), 1500);
}
else if (input.length === 1 && /[a-zA-Z0-9-_]/.test(input)) {
setSearch(s => s + input);
setSel(0);
}
});
return (
<Box flexDirection="column">
<Text bold color={colors.primary}>SKILL MARKETPLACE</Text>
<Text dimColor>{skills.length} skills from {SKILL_SOURCES.length} sources</Text>
{search && (
<Text>Search: <Text color="yellow">{search}</Text> ({filtered.length} results)</Text>
)}
{loading && <Text>Loading marketplace...</Text>}
{error && <Text color="red">{error}</Text>}
{installing && <Text color="yellow">Installing {installing}...</Text>}
{!loading && !installing && filtered.length === 0 && (
<Box marginTop={1}>
<Text dimColor>No skills found{search ? ` matching "${search}"` : ''}.</Text>
</Box>
)}
{!loading && !installing && filtered.length > 0 && (
<Box marginTop={1} flexDirection="column">
{start > 0 && <Text dimColor> ↑ {start} more</Text>}
{visible.map((skill, i) => {
const idx = start + i;
const isSel = idx === sel;
return (
<Box key={`${skill.repo}/${skill.name}`} flexDirection="column">
<Text inverse={isSel}>
{isSel ? symbols.pointer : ' '} {skill.name.padEnd(25)} <Text dimColor>{skill.source}</Text>
</Text>
{isSel && (
<Box flexDirection="column" marginLeft={3}>
<Text dimColor>{skill.description}</Text>
{skill.tags && skill.tags.length > 0 && (
<Text dimColor>Tags: {skill.tags.join(', ')}</Text>
)}
<Text dimColor>Repo: {skill.repo}</Text>
</Box>
)}
</Box>
);
})}
{start + maxVisible < filtered.length && <Text dimColor> ↓ {filtered.length - start - maxVisible} more</Text>}
</Box>
)}
<Box marginTop={1}>
<Text dimColor>Enter=install type=search r=refresh q=quit</Text>
</Box>
</Box>
);
}
+284
View File
@@ -0,0 +1,284 @@
import { useState, useEffect } from 'react';
import { Box, Text, useInput } from 'ink';
import { colors, symbols } from '../theme.js';
import {
ObservationStore,
LearningStore,
getMemoryStatus,
getMemoryPaths,
createMemoryInjector,
type Learning,
} from '@skillkit/core';
interface Props {
cols?: number;
rows?: number;
}
type Tab = 'learnings' | 'observations' | 'search';
export function Memory({ rows = 24 }: Props) {
const [tab, setTab] = useState<Tab>('learnings');
const [learnings, setLearnings] = useState<Learning[]>([]);
const [observationCount, setObservationCount] = useState(0);
const [globalCount, setGlobalCount] = useState(0);
const [loading, setLoading] = useState(true);
const [sel, setSel] = useState(0);
const [expanded, setExpanded] = useState(false);
const [searchQuery, setSearchQuery] = useState('');
const [searchResults, setSearchResults] = useState<Learning[]>([]);
const [isGlobal, setIsGlobal] = useState(false);
const maxVisible = Math.max(5, rows - 10);
const currentList = tab === 'search' ? searchResults : learnings;
const start = Math.max(0, Math.min(sel - Math.floor(maxVisible / 2), currentList.length - maxVisible));
const visible = currentList.slice(start, start + maxVisible);
useEffect(() => {
loadMemory();
}, [isGlobal]);
const loadMemory = () => {
setLoading(true);
try {
const projectPath = process.cwd();
const status = getMemoryStatus(projectPath);
// Load learnings
const store = new LearningStore(
isGlobal ? 'global' : 'project',
isGlobal ? undefined : projectPath
);
setLearnings(store.getAll());
// Get counts
if (status.hasObservations) {
const obsStore = new ObservationStore(projectPath);
setObservationCount(obsStore.count());
} else {
setObservationCount(0);
}
if (status.hasGlobalLearnings) {
const globalStore = new LearningStore('global');
setGlobalCount(globalStore.count());
} else {
setGlobalCount(0);
}
} catch {
setLearnings([]);
setObservationCount(0);
setGlobalCount(0);
}
setLoading(false);
};
const handleSearch = (query: string) => {
if (!query.trim()) {
setSearchResults([]);
return;
}
try {
const projectPath = process.cwd();
const injector = createMemoryInjector(projectPath);
const results = injector.search(query, {
includeGlobal: true,
maxLearnings: 20,
minRelevance: 0,
});
setSearchResults(results.map(r => r.learning));
} catch {
setSearchResults([]);
}
};
useInput((input, key) => {
if (loading) return;
// Tab navigation
if (input === '1') { setTab('learnings'); setSel(0); setExpanded(false); }
else if (input === '2') { setTab('observations'); setSel(0); setExpanded(false); }
else if (input === '3') { setTab('search'); setSel(0); setExpanded(false); }
// List navigation
else if (key.upArrow) {
setSel(i => Math.max(0, i - 1));
setExpanded(false);
}
else if (key.downArrow) {
setSel(i => Math.min(currentList.length - 1, i + 1));
setExpanded(false);
}
// Actions (use 'f' for refresh to avoid conflict with global 'r' for Recommend)
else if (input === 'f') loadMemory();
else if (input === 'g') setIsGlobal(g => !g);
else if (key.return) setExpanded(e => !e);
// Search input (basic)
else if (tab === 'search' && input && input.length === 1 && !key.ctrl && !key.meta) {
const newQuery = searchQuery + input;
setSearchQuery(newQuery);
handleSearch(newQuery);
}
else if (tab === 'search' && key.backspace) {
const newQuery = searchQuery.slice(0, -1);
setSearchQuery(newQuery);
handleSearch(newQuery);
}
});
const ONE_MINUTE = 60_000;
const ONE_HOUR = 3_600_000;
const ONE_DAY = 86_400_000;
function formatDate(iso: string): string {
const d = new Date(iso);
const diff = Date.now() - d.getTime();
if (diff < ONE_MINUTE) return 'Just now';
if (diff < ONE_HOUR) return `${Math.floor(diff / ONE_MINUTE)}m ago`;
if (diff < ONE_DAY) return `${Math.floor(diff / ONE_HOUR)}h ago`;
return d.toLocaleDateString();
}
function formatEffectiveness(eff?: number): string {
if (eff === undefined) return ' -';
return eff.toString().padStart(3) + '%';
}
function getEffectivenessColor(eff?: number): string | undefined {
if (eff === undefined) return undefined;
if (eff >= 70) return 'green';
if (eff >= 40) return 'yellow';
return 'red';
}
const renderLearnings = () => (
<Box flexDirection="column">
{currentList.length === 0 && (
<Box marginTop={1} flexDirection="column">
<Text dimColor>No learnings found.</Text>
<Text dimColor>Run skills to capture learnings, or add manually:</Text>
<Text dimColor> skillkit memory add --title "..." --content "..."</Text>
</Box>
)}
{currentList.length > 0 && (
<Box marginTop={1} flexDirection="column">
{start > 0 && <Text dimColor> {symbols.arrowUp} {start} more</Text>}
{visible.map((learning, i) => {
const idx = start + i;
const isSel = idx === sel;
return (
<Box key={learning.id} flexDirection="column">
<Text inverse={isSel}>
{isSel ? symbols.pointer : ' '}
<Text color={colors.primary}>{symbols.bullet}</Text>
{' '}{learning.title.slice(0, 35).padEnd(35)}{' '}
<Text dimColor>{learning.tags.slice(0, 2).join(', ').slice(0, 15).padEnd(15)}</Text>
{' '}<Text color={getEffectivenessColor(learning.effectiveness)}>{formatEffectiveness(learning.effectiveness)}</Text>
{' '}<Text dimColor>{formatDate(learning.updatedAt)}</Text>
</Text>
{isSel && expanded && (
<Box flexDirection="column" marginLeft={3} marginY={1}>
<Text dimColor>ID: {learning.id.slice(0, 8)}</Text>
<Text dimColor>Scope: {learning.scope}</Text>
<Text dimColor>Source: {learning.source}</Text>
<Text dimColor>Tags: {learning.tags.join(', ')}</Text>
{learning.frameworks && learning.frameworks.length > 0 && (
<Text dimColor>Frameworks: {learning.frameworks.join(', ')}</Text>
)}
<Text dimColor>Uses: {learning.useCount}</Text>
<Box marginTop={1}>
<Text wrap="wrap">{learning.content.slice(0, 300)}{learning.content.length > 300 ? '...' : ''}</Text>
</Box>
</Box>
)}
</Box>
);
})}
{start + maxVisible < currentList.length && (
<Text dimColor> {symbols.arrowDown} {currentList.length - start - maxVisible} more</Text>
)}
</Box>
)}
</Box>
);
const renderObservations = () => (
<Box flexDirection="column" marginTop={1}>
<Text>Session Observations: <Text bold color={colors.primary}>{observationCount}</Text></Text>
<Text dimColor>Observations are raw captures from skill execution.</Text>
{observationCount > 0 && (
<Box marginTop={1} flexDirection="column">
<Text>Compress observations into learnings:</Text>
<Text dimColor> skillkit memory compress</Text>
</Box>
)}
{observationCount >= 50 && (
<Box marginTop={1}>
<Text color="yellow">{symbols.warning} You have many uncompressed observations.</Text>
</Box>
)}
<Box marginTop={1}>
<Text dimColor>Observations are stored at:</Text>
</Box>
<Text dimColor> {getMemoryPaths(process.cwd()).observationsFile}</Text>
</Box>
);
const renderSearch = () => (
<Box flexDirection="column" marginTop={1}>
<Box>
<Text>Search: </Text>
<Text color={colors.primary}>{searchQuery}</Text>
<Text color={colors.secondary}>_</Text>
</Box>
{searchQuery && searchResults.length === 0 && (
<Box marginTop={1}>
<Text dimColor>No results found for "{searchQuery}"</Text>
</Box>
)}
{searchResults.length > 0 && renderLearnings()}
</Box>
);
return (
<Box flexDirection="column">
<Text bold color={colors.primary}>MEMORY</Text>
<Text dimColor>
{isGlobal ? 'Global' : 'Project'}: {learnings.length} learning(s)
{!isGlobal && globalCount > 0 && <Text> | Global: {globalCount}</Text>}
</Text>
{/* Tabs */}
<Box marginTop={1}>
<Text inverse={tab === 'learnings'}>[1] Learnings</Text>
<Text> </Text>
<Text inverse={tab === 'observations'}>[2] Observations</Text>
<Text> </Text>
<Text inverse={tab === 'search'}>[3] Search</Text>
</Box>
{loading && <Box marginTop={1}><Text>Loading...</Text></Box>}
{!loading && tab === 'learnings' && renderLearnings()}
{!loading && tab === 'observations' && renderObservations()}
{!loading && tab === 'search' && renderSearch()}
<Box marginTop={1}>
<Text dimColor>
Enter=expand g=toggle global f=refresh 1-3=tabs
</Text>
</Box>
</Box>
);
}
+232
View File
@@ -0,0 +1,232 @@
import { useState, useEffect } from 'react';
import { Box, Text, useInput } from 'ink';
import { colors, symbols } from '../theme.js';
interface PluginInfo {
name: string;
version: string;
description?: string;
author?: string;
enabled: boolean;
translators?: string[];
providers?: string[];
commands?: string[];
}
interface Props {
cols?: number;
rows?: number;
}
export function Plugins({ rows = 24 }: Props) {
const [plugins, setPlugins] = useState<PluginInfo[]>([]);
const [loading, setLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
const [sel, setSel] = useState(0);
const [message, setMessage] = useState<string | null>(null);
const maxVisible = Math.max(5, rows - 12);
const start = Math.max(0, Math.min(sel - Math.floor(maxVisible / 2), plugins.length - maxVisible));
const visible = plugins.slice(start, start + maxVisible);
useEffect(() => {
loadPlugins();
}, []);
const loadPlugins = async () => {
setLoading(true);
setError(null);
try {
const { createPluginManager, loadPluginsFromDirectory } = await import('@skillkit/core');
const { join } = await import('node:path');
const manager = createPluginManager(process.cwd());
// Load plugins from directory first to populate the manager
const pluginsDir = join(process.cwd(), '.skillkit', 'plugins');
try {
const loadedPlugins = await loadPluginsFromDirectory(pluginsDir);
for (const plugin of loadedPlugins) {
if (!manager.getPlugin(plugin.metadata.name)) {
await manager.register(plugin);
}
}
} catch (err: unknown) {
// Only ignore ENOENT (directory doesn't exist), rethrow other errors
if (err && typeof err === 'object' && 'code' in err && err.code !== 'ENOENT') {
throw err;
}
}
const allPlugins = manager.listPlugins();
const pluginInfos: PluginInfo[] = allPlugins.map(p => {
const plugin = manager.getPlugin(p.name);
return {
name: p.name,
version: p.version,
description: p.description,
author: p.author,
enabled: manager.isPluginEnabled(p.name),
translators: plugin?.translators?.map(t => t.agentType as string),
providers: plugin?.providers?.map(pr => pr.providerName),
commands: plugin?.commands?.map(c => c.name),
};
});
setPlugins(pluginInfos);
} catch (e) {
setError(e instanceof Error ? e.message : 'Failed to load plugins');
}
setLoading(false);
};
const togglePlugin = async (pluginName: string, currentEnabled: boolean) => {
setLoading(true);
setMessage(null);
try {
const { createPluginManager, loadPluginsFromDirectory } = await import('@skillkit/core');
const { join } = await import('node:path');
const manager = createPluginManager(process.cwd());
// Load plugins from directory first so enable/disable can find them
const pluginsDir = join(process.cwd(), '.skillkit', 'plugins');
try {
const loadedPlugins = await loadPluginsFromDirectory(pluginsDir);
for (const plugin of loadedPlugins) {
if (!manager.getPlugin(plugin.metadata.name)) {
await manager.register(plugin);
}
}
} catch (err: unknown) {
// Only ignore ENOENT (directory doesn't exist), rethrow other errors
if (err && typeof err === 'object' && 'code' in err && err.code !== 'ENOENT') {
throw err;
}
}
if (currentEnabled) {
manager.disablePlugin(pluginName);
setMessage(`Disabled: ${pluginName}`);
} else {
manager.enablePlugin(pluginName);
setMessage(`Enabled: ${pluginName}`);
}
// Reload
await loadPlugins();
} catch (e) {
setError(e instanceof Error ? e.message : 'Toggle failed');
setLoading(false);
}
};
useInput((input, key) => {
if (loading) return;
if (plugins.length === 0 && (key.upArrow || key.downArrow)) return;
if (key.upArrow) setSel(i => Math.max(0, i - 1));
else if (key.downArrow) setSel(i => Math.min(Math.max(0, plugins.length - 1), i + 1));
else if (input === 'r') loadPlugins();
else if (input === 'e' && plugins[sel]) {
togglePlugin(plugins[sel].name, plugins[sel].enabled);
}
else if (key.return && plugins[sel]) {
togglePlugin(plugins[sel].name, plugins[sel].enabled);
}
});
if (loading) {
return (
<Box flexDirection="column" padding={1}>
<Text color={colors.primary} bold>Plugin Manager</Text>
<Box marginTop={1}>
<Text color={colors.secondaryDim}>{symbols.spinner[0]} Loading...</Text>
</Box>
</Box>
);
}
return (
<Box flexDirection="column" padding={1}>
<Text color={colors.primary} bold>Plugin Manager</Text>
<Text color={colors.secondaryDim} dimColor>Manage SkillKit extensions</Text>
{error && (
<Box marginTop={1}>
<Text color="red">{symbols.error} {error}</Text>
</Box>
)}
{message && (
<Box marginTop={1}>
<Text color="green">{symbols.success} {message}</Text>
</Box>
)}
<Box marginTop={1} flexDirection="column">
<Text color={colors.secondaryDim} bold>
Installed Plugins ({plugins.length})
</Text>
{plugins.length === 0 ? (
<Box marginTop={1} flexDirection="column">
<Text color={colors.secondaryDim} dimColor>No plugins installed.</Text>
<Text color={colors.secondaryDim} dimColor>
Use: skillkit plugin install --source &lt;path-or-package&gt;
</Text>
</Box>
) : (
<Box flexDirection="column" marginTop={1}>
{visible.map((plugin, i) => {
const actualIndex = start + i;
const isSelected = actualIndex === sel;
const statusColor = plugin.enabled ? 'green' : 'gray';
const statusText = plugin.enabled ? 'enabled' : 'disabled';
return (
<Box key={plugin.name} flexDirection="column">
<Text>
{isSelected ? symbols.pointer : ' '}{' '}
<Text color={isSelected ? colors.primary : colors.secondaryDim} bold={isSelected}>
{plugin.name}
</Text>
<Text dimColor> v{plugin.version}</Text>
<Text color={statusColor}> [{statusText}]</Text>
</Text>
{isSelected && (
<Box flexDirection="column" marginLeft={3}>
{plugin.description && (
<Text color={colors.secondaryDim} dimColor>{plugin.description}</Text>
)}
{plugin.author && (
<Text dimColor>Author: {plugin.author}</Text>
)}
{plugin.translators && plugin.translators.length > 0 && (
<Text dimColor>Translators: {plugin.translators.join(', ')}</Text>
)}
{plugin.providers && plugin.providers.length > 0 && (
<Text dimColor>Providers: {plugin.providers.join(', ')}</Text>
)}
{plugin.commands && plugin.commands.length > 0 && (
<Text dimColor>Commands: {plugin.commands.join(', ')}</Text>
)}
</Box>
)}
</Box>
);
})}
</Box>
)}
</Box>
<Box marginTop={1} borderStyle="single" borderColor={colors.borderDim} paddingX={1}>
<Text dimColor>
[↑↓] Navigate [e/Enter] Toggle Enable/Disable [r] Refresh
</Text>
</Box>
</Box>
);
}
+162 -14
View File
@@ -1,44 +1,192 @@
import { useState } from 'react';
import { useState, useEffect } from 'react';
import { Box, Text, useInput } from 'ink';
import TextInput from 'ink-text-input';
import { colors, symbols } from '../theme.js';
import { loadConfig, saveConfig, AgentType as AgentTypeSchema, type SkillkitConfig, type AgentType } from '@skillkit/core';
interface Props {
cols?: number;
rows?: number;
}
const SETTINGS = [
{ id: 'agent', label: 'Default Agent', value: 'auto-detect' },
{ id: 'sync', label: 'Auto Sync', value: 'disabled' },
{ id: 'cache', label: 'Cache Dir', value: '~/.skillkit/cache' },
interface Setting {
id: keyof SkillkitConfig | 'agent' | 'autoSync' | 'cacheDir';
label: string;
type: 'select' | 'toggle' | 'text';
options?: string[];
}
// Get all valid agent types from the Zod schema
const ALL_AGENTS: AgentType[] = AgentTypeSchema.options;
const SETTINGS: Setting[] = [
{ id: 'agent', label: 'Default Agent', type: 'select', options: ['auto-detect', ...ALL_AGENTS] },
{ id: 'autoSync', label: 'Auto Sync', type: 'toggle' },
{ id: 'cacheDir', label: 'Cache Dir', type: 'text' },
];
export function Settings({}: Props) {
export function Settings(_props: Props) {
const [config, setConfig] = useState<SkillkitConfig | null>(null);
const [sel, setSel] = useState(0);
const [editing, setEditing] = useState(false);
const [editValue, setEditValue] = useState('');
const [saved, setSaved] = useState(false);
const [error, setError] = useState<string | null>(null);
useInput((_, key) => {
if (key.upArrow) setSel(i => Math.max(0, i - 1));
else if (key.downArrow) setSel(i => Math.min(SETTINGS.length - 1, i + 1));
// Load config on mount
useEffect(() => {
try {
const loaded = loadConfig();
setConfig(loaded);
} catch (err) {
setError(`Failed to load config: ${err}`);
}
}, []);
const getCurrentValue = (setting: Setting): string => {
if (!config) return '';
switch (setting.id) {
case 'agent':
// Map 'universal' back to 'auto-detect' for display consistency
return config.agent === 'universal' ? 'auto-detect' : (config.agent || 'auto-detect');
case 'autoSync':
return config.autoSync ? 'enabled' : 'disabled';
case 'cacheDir':
return config.cacheDir || '~/.skillkit/cache';
default:
return '';
}
};
const handleSave = (setting: Setting, value: string) => {
if (!config) return;
const newConfig = { ...config };
switch (setting.id) {
case 'agent':
if (value === 'auto-detect') {
newConfig.agent = 'universal';
} else {
newConfig.agent = value as AgentType;
}
break;
case 'autoSync':
newConfig.autoSync = value === 'enabled';
break;
case 'cacheDir':
newConfig.cacheDir = value || undefined;
break;
}
try {
saveConfig(newConfig, false);
setConfig(newConfig);
setSaved(true);
setTimeout(() => setSaved(false), 2000);
} catch (err) {
setError(`Failed to save: ${err}`);
setTimeout(() => setError(null), 3000);
}
};
useInput((input, key) => {
if (editing) {
if (key.return) {
handleSave(SETTINGS[sel], editValue);
setEditing(false);
} else if (key.escape) {
setEditing(false);
}
return;
}
if (key.upArrow) {
setSel(i => Math.max(0, i - 1));
} else if (key.downArrow) {
setSel(i => Math.min(SETTINGS.length - 1, i + 1));
} else if (key.return || input === ' ') {
const setting = SETTINGS[sel];
if (setting.type === 'toggle') {
const current = getCurrentValue(setting);
const newValue = current === 'enabled' ? 'disabled' : 'enabled';
handleSave(setting, newValue);
} else if (setting.type === 'select' && setting.options) {
const current = getCurrentValue(setting);
const idx = setting.options.indexOf(current);
const nextIdx = (idx + 1) % setting.options.length;
handleSave(setting, setting.options[nextIdx]);
} else if (setting.type === 'text') {
setEditValue(getCurrentValue(setting));
setEditing(true);
}
}
});
if (!config) {
return (
<Box flexDirection="column">
<Text bold color={colors.primary}>SETTINGS</Text>
{error ? (
<Text color={colors.danger}>{symbols.error} {error}</Text>
) : (
<Text dimColor>Loading...</Text>
)}
</Box>
);
}
return (
<Box flexDirection="column">
<Text bold color={colors.primary}>SETTINGS</Text>
<Text dimColor>Configure SkillKit</Text>
<Text dimColor>Configure SkillKit (changes save automatically)</Text>
<Box marginTop={1} flexDirection="column">
{SETTINGS.map((s, i) => {
const isSel = i === sel;
const value = getCurrentValue(s);
const isEditing = editing && isSel;
return (
<Text key={s.id} inverse={isSel}>
{isSel ? symbols.pointer : ' '}{s.label.padEnd(16)} <Text color={colors.secondaryDim}>{s.value}</Text>
</Text>
<Box key={s.id}>
<Text inverse={isSel && !isEditing}>
{isSel ? symbols.pointer : ' '}{s.label.padEnd(16)}
</Text>
{isEditing ? (
<Box marginLeft={1}>
<TextInput
value={editValue}
onChange={setEditValue}
onSubmit={() => {
handleSave(s, editValue);
setEditing(false);
}}
/>
</Box>
) : (
<Text color={colors.secondaryDim}> {value}</Text>
)}
{s.type === 'toggle' && isSel && !isEditing && (
<Text dimColor> (space to toggle)</Text>
)}
{s.type === 'select' && isSel && !isEditing && (
<Text dimColor> (enter to cycle)</Text>
)}
</Box>
);
})}
</Box>
<Box marginTop={1}>
<Text dimColor>Enter=edit q=quit</Text>
{saved && <Text color={colors.success}>{symbols.check} Settings saved</Text>}
{error && <Text color={colors.danger}>{symbols.error} {error}</Text>}
{!saved && !error && (
<Text dimColor>
{editing ? 'Enter=save Esc=cancel' : 'Enter/Space=edit q=quit'}
</Text>
)}
</Box>
</Box>
);
+221
View File
@@ -0,0 +1,221 @@
import { useState, useEffect } from 'react';
import { Box, Text, useInput } from 'ink';
import { colors, symbols } from '../theme.js';
interface SharedSkill {
name: string;
version: string;
description?: string;
author: string;
downloads?: number;
tags?: string[];
}
interface TeamConfig {
teamId: string;
teamName: string;
registryUrl: string;
}
interface Props {
cols?: number;
rows?: number;
}
export function Team({ rows = 24 }: Props) {
const [config, setConfig] = useState<TeamConfig | null>(null);
const [skills, setSkills] = useState<SharedSkill[]>([]);
const [loading, setLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
const [sel, setSel] = useState(0);
const [message, setMessage] = useState<string | null>(null);
const maxVisible = Math.max(5, rows - 12);
const start = Math.max(0, Math.min(sel - Math.floor(maxVisible / 2), skills.length - maxVisible));
const visible = skills.slice(start, start + maxVisible);
useEffect(() => {
loadTeam();
}, []);
const loadTeam = async () => {
setLoading(true);
setError(null);
try {
const { createTeamManager } = await import('@skillkit/core');
const manager = createTeamManager(process.cwd());
const teamConfig = manager.load();
if (!teamConfig) {
setConfig(null);
setSkills([]);
setError('Team not initialized. Run `skillkit team init` first.');
} else {
setConfig(teamConfig);
const sharedSkills = manager.listSharedSkills();
setSkills(sharedSkills);
setSel(s => Math.min(s, Math.max(0, sharedSkills.length - 1)));
}
} catch (e) {
setError(e instanceof Error ? e.message : 'Failed to load team');
}
setLoading(false);
};
const syncTeam = async () => {
if (!config) return;
setLoading(true);
setMessage(null);
try {
const { createTeamManager } = await import('@skillkit/core');
const manager = createTeamManager(process.cwd());
manager.load(); // Load config before sync
const result = await manager.sync();
const changes = [...result.added, ...result.updated];
if (changes.length > 0) {
setMessage(`Synced: ${changes.join(', ')}`);
} else {
setMessage('Already up to date');
}
// Reload skills
const sharedSkills = manager.listSharedSkills();
setSkills(sharedSkills);
setSel(s => Math.min(s, Math.max(0, sharedSkills.length - 1)));
} catch (e) {
setError(e instanceof Error ? e.message : 'Sync failed');
}
setLoading(false);
};
const importSkill = async (skillName: string) => {
if (!config) return;
setLoading(true);
setMessage(null);
try {
const { createTeamManager } = await import('@skillkit/core');
const manager = createTeamManager(process.cwd());
manager.load(); // Load config before import
const result = await manager.importSkill(skillName, { overwrite: false });
if (result.success) {
setMessage(`Imported: ${skillName}`);
} else {
setError(result.error || 'Import failed');
}
} catch (e) {
setError(e instanceof Error ? e.message : 'Import failed');
}
setLoading(false);
};
useInput((input, key) => {
if (loading) return;
if (skills.length === 0 && (key.upArrow || key.downArrow)) return;
if (key.upArrow) setSel(i => Math.max(0, i - 1));
else if (key.downArrow) setSel(i => Math.min(Math.max(0, skills.length - 1), i + 1));
else if (input === 'r') loadTeam();
else if (input === 's') syncTeam();
else if (key.return && skills[sel]) {
importSkill(skills[sel].name);
}
});
if (loading) {
return (
<Box flexDirection="column" padding={1}>
<Text color={colors.primary} bold>Team Collaboration</Text>
<Box marginTop={1}>
<Text color={colors.secondaryDim}>{symbols.spinner[0]} Loading...</Text>
</Box>
</Box>
);
}
if (!config) {
return (
<Box flexDirection="column" padding={1}>
<Text color={colors.primary} bold>Team Collaboration</Text>
<Box marginTop={1} flexDirection="column">
<Text color={colors.secondaryDim}>{symbols.warning} Team not initialized</Text>
<Text color={colors.secondaryDim} dimColor>
Run: skillkit team init --name "Team Name" --registry &lt;url&gt;
</Text>
</Box>
<Box marginTop={1}>
<Text dimColor>[r] Refresh</Text>
</Box>
</Box>
);
}
return (
<Box flexDirection="column" padding={1}>
<Text color={colors.primary} bold>Team: {config.teamName}</Text>
<Text color={colors.secondaryDim} dimColor>Registry: {config.registryUrl}</Text>
{error && (
<Box marginTop={1}>
<Text color="red">{symbols.error} {error}</Text>
</Box>
)}
{message && (
<Box marginTop={1}>
<Text color="green">{symbols.success} {message}</Text>
</Box>
)}
<Box marginTop={1} flexDirection="column">
<Text color={colors.secondaryDim} bold>
Shared Skills ({skills.length})
</Text>
{skills.length === 0 ? (
<Text color={colors.secondaryDim} dimColor>
No shared skills. Use `skillkit team share --name &lt;skill&gt;` to share.
</Text>
) : (
<Box flexDirection="column" marginTop={1}>
{visible.map((skill, i) => {
const actualIndex = start + i;
const isSelected = actualIndex === sel;
return (
<Box key={skill.name} flexDirection="column">
<Text>
{isSelected ? symbols.pointer : ' '}{' '}
<Text color={isSelected ? colors.primary : colors.secondaryDim} bold={isSelected}>
{skill.name}
</Text>
<Text dimColor> v{skill.version}</Text>
<Text dimColor> by {skill.author}</Text>
{skill.downloads !== undefined && (
<Text dimColor> | {skill.downloads} downloads</Text>
)}
</Text>
{skill.description && isSelected && (
<Text color={colors.secondaryDim} dimColor> {skill.description}</Text>
)}
</Box>
);
})}
</Box>
)}
</Box>
<Box marginTop={1} borderStyle="single" borderColor={colors.borderDim} paddingX={1}>
<Text dimColor>
[↑↓] Navigate [Enter] Import [s] Sync [r] Refresh
</Text>
</Box>
</Box>
);
}
+96
View File
@@ -0,0 +1,96 @@
import { useState, useEffect } from 'react';
import { Box, Text, useInput } from 'ink';
import { colors, symbols } from '../theme.js';
import { listWorkflows, type Workflow as WorkflowType } from '@skillkit/core';
interface Props {
cols?: number;
rows?: number;
}
export function Workflow({ rows = 24 }: Props) {
const [workflows, setWorkflows] = useState<WorkflowType[]>([]);
const [loading, setLoading] = useState(true);
const [sel, setSel] = useState(0);
const [running, setRunning] = useState<string | null>(null);
const [error, setError] = useState<string | null>(null);
const maxVisible = Math.max(5, rows - 8);
const start = Math.max(0, Math.min(sel - Math.floor(maxVisible / 2), workflows.length - maxVisible));
const visible = workflows.slice(start, start + maxVisible);
useEffect(() => {
loadWorkflows();
}, []);
const loadWorkflows = () => {
setLoading(true);
setError(null);
try {
const wfs = listWorkflows(process.cwd());
setWorkflows(wfs);
} catch (e) {
setError(e instanceof Error ? e.message : 'Failed to load workflows');
}
setLoading(false);
};
useInput((input, key) => {
if (loading || running) return;
if (key.upArrow) setSel(i => Math.max(0, i - 1));
else if (key.downArrow) setSel(i => Math.min(workflows.length - 1, i + 1));
else if (input === 'r') loadWorkflows();
else if (key.return && workflows[sel]) {
// Simulate running workflow
setRunning(workflows[sel].name);
setTimeout(() => setRunning(null), 2000);
}
});
return (
<Box flexDirection="column">
<Text bold color={colors.primary}>WORKFLOWS</Text>
<Text dimColor>{workflows.length} workflow(s) found</Text>
{loading && <Text>Loading workflows...</Text>}
{error && <Text color="red">{error}</Text>}
{running && <Text color="yellow">Running: {running}...</Text>}
{!loading && !running && workflows.length === 0 && (
<Box marginTop={1} flexDirection="column">
<Text dimColor>No workflows found.</Text>
<Text dimColor>Create one with: skillkit workflow create</Text>
</Box>
)}
{!loading && !running && workflows.length > 0 && (
<Box marginTop={1} flexDirection="column">
{start > 0 && <Text dimColor> ↑ {start} more</Text>}
{visible.map((wf, i) => {
const idx = start + i;
const isSel = idx === sel;
return (
<Box key={wf.name} flexDirection="column">
<Text inverse={isSel}>
{isSel ? symbols.pointer : ' '} {wf.name}
</Text>
{isSel && wf.description && (
<Text dimColor> {wf.description}</Text>
)}
{isSel && (
<Text dimColor> {wf.waves.length} wave(s), {wf.waves.reduce((acc, w) => acc + w.skills.length, 0)} skill(s)</Text>
)}
</Box>
);
})}
{start + maxVisible < workflows.length && <Text dimColor> ↓ {workflows.length - start - maxVisible} more</Text>}
</Box>
)}
<Box marginTop={1}>
<Text dimColor>Enter=run r=refresh q=quit</Text>
</Box>
</Box>
);
}
+7
View File
@@ -6,3 +6,10 @@ export { Settings } from './Settings.js';
export { Recommend } from './Recommend.js';
export { Translate } from './Translate.js';
export { Context } from './Context.js';
export { Memory } from './Memory.js';
export { Workflow } from './Workflow.js';
export { Execute } from './Execute.js';
export { History } from './History.js';
export { Marketplace } from './Marketplace.js';
export { Team } from './Team.js';
export { Plugins } from './Plugins.js';
+6
View File
@@ -19,6 +19,12 @@ export const symbols = {
check: chalk.white('✓'),
star: '★',
spinner: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'],
arrowUp: '↑',
arrowDown: '↓',
success: '✓',
error: '✗',
warning: '⚠',
info: 'ℹ',
};
export const logo = `
+3
View File
@@ -103,6 +103,9 @@ importers:
ora:
specifier: ^8.1.0
version: 8.2.0
yaml:
specifier: ^2.7.0
version: 2.8.2
devDependencies:
'@types/node':
specifier: ^22.10.5
+1
View File
@@ -38,6 +38,7 @@ const POPULAR_REPOS: RepoInfo[] = [
{ source: 'giuseppe-trisciuoglio/developer-kit', name: 'Shadcn / Radix' },
{ source: 'openrouterteam/agent-skills', name: 'OpenRouter SDK' },
{ source: 'intellectronica/agent-skills', name: 'Context7' },
{ source: 'alirezarezvani/claude-skills', name: 'Alireza Rezvani' },
];
interface FetchedSkill {