diff --git a/apps/skillkit/src/cli.ts b/apps/skillkit/src/cli.ts index 8474b4ff..d329860f 100644 --- a/apps/skillkit/src/cli.ts +++ b/apps/skillkit/src/cli.ts @@ -19,6 +19,16 @@ import { TranslateCommand, ContextCommand, RecommendCommand, + StatusCommand, + PauseCommand, + ResumeCommand, + WorkflowRunCommand, + WorkflowListCommand, + WorkflowCreateCommand, + RunCommand, + TestCommand, + MarketplaceCommand, + MemoryCommand, } from '@skillkit/cli'; const __filename = fileURLToPath(import.meta.url); @@ -51,5 +61,15 @@ 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.runExit(process.argv.slice(2)); diff --git a/packages/cli/package.json b/packages/cli/package.json index 88681123..a43b32f2 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -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", diff --git a/packages/cli/src/commands/index.ts b/packages/cli/src/commands/index.ts index 63ba53d4..33d394cd 100644 --- a/packages/cli/src/commands/index.ts +++ b/packages/cli/src/commands/index.ts @@ -13,3 +13,11 @@ 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'; diff --git a/packages/cli/src/commands/marketplace.ts b/packages/cli/src/commands/marketplace.ts new file mode 100644 index 00000000..4b3a9b80 --- /dev/null +++ b/packages/cli/src/commands/marketplace.ts @@ -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 { + 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): Promise { + 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 " 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): Promise { + 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): Promise { + 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): Promise { + 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): Promise { + 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; + } +} diff --git a/packages/cli/src/commands/memory.ts b/packages/cli/src/commands/memory.ts new file mode 100644 index 00000000..a8672b02 --- /dev/null +++ b/packages/cli/src/commands/memory.ts @@ -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 '], + ['Compress observations', '$0 memory compress'], + ['Export as skill', '$0 memory export --name my-skill'], + ['Clear session', '$0 memory clear'], + ['Add manual learning', '$0 memory add --title "..." --content "..."'], + ['Rate effectiveness', '$0 memory rate 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 { + 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 { + 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 { + 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 { + 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 { + const id = this.arg; + if (!id) { + console.error(chalk.red('Error: Learning ID is required')); + console.log(chalk.gray('Usage: skillkit memory show ')); + 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 { + 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 { + const id = this.arg; + if (!id) { + console.error(chalk.red('Error: Learning ID is required')); + console.log(chalk.gray('Usage: skillkit memory export --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 { + 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 ')); + 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 { + 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 { + 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 { + const id = this.arg; + if (!id) { + console.error(chalk.red('Error: Learning ID is required')); + console.log(chalk.gray('Usage: skillkit memory rate ')); + 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 ')); + 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 { + 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'); + } +} diff --git a/packages/cli/src/commands/pause.ts b/packages/cli/src/commands/pause.ts new file mode 100644 index 00000000..e4feed13 --- /dev/null +++ b/packages/cli/src/commands/pause.ts @@ -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 { + 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; + } + } +} diff --git a/packages/cli/src/commands/recommend.ts b/packages/cli/src/commands/recommend.ts index 23c545af..0b29f843 100644 --- a/packages/cli/src/commands/recommend.ts +++ b/packages/cli/src/commands/recommend.ts @@ -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 { + 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, - }, - ]; -} diff --git a/packages/cli/src/commands/resume.ts b/packages/cli/src/commands/resume.ts new file mode 100644 index 00000000..7016c4e1 --- /dev/null +++ b/packages/cli/src/commands/resume.ts @@ -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 { + 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 ')); + 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; + } + } +} diff --git a/packages/cli/src/commands/run.ts b/packages/cli/src/commands/run.ts new file mode 100644 index 00000000..ff900a4d --- /dev/null +++ b/packages/cli/src/commands/run.ts @@ -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 { + 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 { + // 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 ')); + 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 | null): ExecutableTask[] | undefined { + if (!frontmatter?.tasks || !Array.isArray(frontmatter.tasks)) { + return undefined; + } + + return frontmatter.tasks.map((task: Record, 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`; + } +} diff --git a/packages/cli/src/commands/status.ts b/packages/cli/src/commands/status.ts new file mode 100644 index 00000000..6d8c494a --- /dev/null +++ b/packages/cli/src/commands/status.ts @@ -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 { + 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 " 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`; + } +} diff --git a/packages/cli/src/commands/test.ts b/packages/cli/src/commands/test.ts new file mode 100644 index 00000000..a58c2b2f --- /dev/null +++ b/packages/cli/src/commands/test.ts @@ -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 { + 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; + + if (!frontmatter.tests) { + return null; + } + + return createTestSuiteFromFrontmatter(skillName, frontmatter); + } catch { + return null; + } + } +} diff --git a/packages/cli/src/commands/workflow/create.ts b/packages/cli/src/commands/workflow/create.ts new file mode 100644 index 00000000..73cd561c --- /dev/null +++ b/packages/cli/src/commands/workflow/create.ts @@ -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 { + 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; + } +} diff --git a/packages/cli/src/commands/workflow/index.ts b/packages/cli/src/commands/workflow/index.ts new file mode 100644 index 00000000..848fef13 --- /dev/null +++ b/packages/cli/src/commands/workflow/index.ts @@ -0,0 +1,4 @@ +// Workflow command exports +export { WorkflowRunCommand } from './run.js'; +export { WorkflowListCommand } from './list.js'; +export { WorkflowCreateCommand } from './create.js'; diff --git a/packages/cli/src/commands/workflow/list.ts b/packages/cli/src/commands/workflow/list.ts new file mode 100644 index 00000000..67df9ba4 --- /dev/null +++ b/packages/cli/src/commands/workflow/list.ts @@ -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 { + const targetPath = resolve(this.projectPath || process.cwd()); + + let workflows: ReturnType; + 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 ')); + + return 0; + } +} diff --git a/packages/cli/src/commands/workflow/run.ts b/packages/cli/src/commands/workflow/run.ts new file mode 100644 index 00000000..069f2920 --- /dev/null +++ b/packages/cli/src/commands/workflow/run.ts @@ -0,0 +1,204 @@ +import { Command, Option } from 'clipanion'; +import { resolve } from 'node:path'; +import chalk from 'chalk'; +import ora from 'ora'; +import { + loadWorkflowByName, + loadWorkflow, + validateWorkflow, + createWorkflowOrchestrator, +} 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)', + }); + + async execute(): Promise { + 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 orchestrator with mock executor (for now) + const orchestrator = createWorkflowOrchestrator( + async (_skillName, _config) => { + // TODO: Integrate with actual skill execution + // For now, simulate execution + await new Promise((resolve) => setTimeout(resolve, 500)); + return { success: true }; + }, + (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 }> }): 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.')); + } +} diff --git a/packages/core/src/cicd/index.ts b/packages/core/src/cicd/index.ts new file mode 100644 index 00000000..b964d2aa --- /dev/null +++ b/packages/core/src/cicd/index.ts @@ -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'; diff --git a/packages/core/src/cicd/templates.ts b/packages/core/src/cicd/templates.ts new file mode 100644 index 00000000..b6765a53 --- /dev/null +++ b/packages/core/src/cicd/templates.ts @@ -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' }, + ]; +} diff --git a/packages/core/src/context/index.ts b/packages/core/src/context/index.ts index 6c7afcc9..a55ec89f 100644 --- a/packages/core/src/context/index.ts +++ b/packages/core/src/context/index.ts @@ -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'; diff --git a/packages/core/src/context/loader.ts b/packages/core/src/context/loader.ts new file mode 100644 index 00000000..84253377 --- /dev/null +++ b/packages/core/src/context/loader.ts @@ -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); +} diff --git a/packages/core/src/executor/agents.ts b/packages/core/src/executor/agents.ts new file mode 100644 index 00000000..d496fc65 --- /dev/null +++ b/packages/core/src/executor/agents.ts @@ -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; + /** 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 { + 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 { + 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; + } = {} +): Promise { + 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 { + 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 +`; +} diff --git a/packages/core/src/executor/engine.ts b/packages/core/src/executor/engine.ts new file mode 100644 index 00000000..ebd3204b --- /dev/null +++ b/packages/core/src/executor/engine.ts @@ -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 { + 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[] = 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 { + 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 { + 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 { + 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 { + 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); +} diff --git a/packages/core/src/executor/index.ts b/packages/core/src/executor/index.ts new file mode 100644 index 00000000..1003e2ca --- /dev/null +++ b/packages/core/src/executor/index.ts @@ -0,0 +1,26 @@ +/** + * 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'; diff --git a/packages/core/src/executor/types.ts b/packages/core/src/executor/types.ts new file mode 100644 index 00000000..bacc88f0 --- /dev/null +++ b/packages/core/src/executor/types.ts @@ -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:, matches:) */ + 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; +} + +/** + * 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; diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index 17884746..a4973234 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -18,3 +18,24 @@ 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'; diff --git a/packages/core/src/marketplace/aggregator.ts b/packages/core/src/marketplace/aggregator.ts new file mode 100644 index 00000000..fcedb081 --- /dev/null +++ b/packages/core/src/marketplace/aggregator.ts @@ -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 { + 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, source)); + } + return skills; + } + + const dataObj = data as Record; + if (dataObj.skills && Array.isArray(dataObj.skills)) { + for (const item of dataObj.skills) { + skills.push(this.parseSkillEntry(item as Record, 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, + 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 = { + 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 { + 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 { + // 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 { + 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 { + const index = await this.getIndex(); + return index.skills.find((s) => s.id === id) || null; + } + + /** + * Get skill content + */ + async getSkillContent(skill: MarketplaceSkill): Promise { + 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(); + + 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); +} diff --git a/packages/core/src/marketplace/index.ts b/packages/core/src/marketplace/index.ts new file mode 100644 index 00000000..e4999394 --- /dev/null +++ b/packages/core/src/marketplace/index.ts @@ -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'; diff --git a/packages/core/src/marketplace/types.ts b/packages/core/src/marketplace/types.ts new file mode 100644 index 00000000..efc103df --- /dev/null +++ b/packages/core/src/marketplace/types.ts @@ -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; diff --git a/packages/core/src/memory/__tests__/compressor.test.ts b/packages/core/src/memory/__tests__/compressor.test.ts new file mode 100644 index 00000000..d5198967 --- /dev/null +++ b/packages/core/src/memory/__tests__/compressor.test.ts @@ -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 => ({ + 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 => ({ + 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); + }); +}); diff --git a/packages/core/src/memory/__tests__/injector.test.ts b/packages/core/src/memory/__tests__/injector.test.ts new file mode 100644 index 00000000..efb818ae --- /dev/null +++ b/packages/core/src/memory/__tests__/injector.test.ts @@ -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 => ({ + 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 => ({ + 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(''); + expect(result.formattedContent).toContain(''); + } + }); + + 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(''); + } + }); + + 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