@roj-ai/sdk 0.0.2

package/src/plugins/skills/discovery.test.ts

@@ -0,0 +1,395 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { mkdir, rm, writeFile } from 'node:fs/promises'
+import * as path from 'node:path'
+import { createNodeFileSystem } from '~/testing/node-platform.js'
+import { discoverSkills, loadSkillContent, parseSkillFile, parseSkillFrontmatter } from './discovery.js'
+
+const testFs = createNodeFileSystem()
+
+// ============================================================================
+// Test Setup
+// ============================================================================
+
+const TEST_DIR = path.join(import.meta.dir, '__test_skills__')
+
+beforeEach(async () => {
+	await mkdir(TEST_DIR, { recursive: true })
+})
+
+afterEach(async () => {
+	await rm(TEST_DIR, { recursive: true, force: true })
+})
+
+// ============================================================================
+// parseSkillFrontmatter tests
+// ============================================================================
+
+describe('parseSkillFrontmatter', () => {
+	it('parses valid frontmatter with name and description', () => {
+		const content = `---
+name: research
+description: Structured research workflow
+---
+# Research Skill
+Some content here...`
+
+		const result = parseSkillFrontmatter(content)
+		expect(result.ok).toBe(true)
+		if (result.ok) {
+			expect(result.value.name).toBe('research')
+			expect(result.value.description).toBe('Structured research workflow')
+		}
+	})
+
+	it('parses quoted values', () => {
+		const content = `---
+name: "code-review"
+description: 'Code review workflow'
+---
+Content...`
+
+		const result = parseSkillFrontmatter(content)
+		expect(result.ok).toBe(true)
+		if (result.ok) {
+			expect(result.value.name).toBe('code-review')
+			expect(result.value.description).toBe('Code review workflow')
+		}
+	})
+
+	it('fails when frontmatter does not start with ---', () => {
+		const content = `name: research
+description: Test
+---
+Content`
+
+		const result = parseSkillFrontmatter(content)
+		expect(result.ok).toBe(false)
+		if (!result.ok) {
+			expect(result.error.message).toContain('must start with ---')
+		}
+	})
+
+	it('fails when closing --- is missing', () => {
+		const content = `---
+name: research
+description: Test
+Content without closing delimiter`
+
+		const result = parseSkillFrontmatter(content)
+		expect(result.ok).toBe(false)
+		if (!result.ok) {
+			expect(result.error.message).toContain('Missing closing ---')
+		}
+	})
+
+	it('fails when name is missing', () => {
+		const content = `---
+description: Test description
+---
+Content`
+
+		const result = parseSkillFrontmatter(content)
+		expect(result.ok).toBe(false)
+		if (!result.ok) {
+			expect(result.error.message).toContain('Missing required "name"')
+		}
+	})
+
+	it('fails when description is missing', () => {
+		const content = `---
+name: test-skill
+---
+Content`
+
+		const result = parseSkillFrontmatter(content)
+		expect(result.ok).toBe(false)
+		if (!result.ok) {
+			expect(result.error.message).toContain('Missing required "description"')
+		}
+	})
+
+	it('ignores comments in frontmatter', () => {
+		const content = `---
+# This is a comment
+name: test
+description: Test skill
+# Another comment
+---
+Content`
+
+		const result = parseSkillFrontmatter(content)
+		expect(result.ok).toBe(true)
+		if (result.ok) {
+			expect(result.value.name).toBe('test')
+		}
+	})
+})
+
+// ============================================================================
+// parseSkillFile tests
+// ============================================================================
+
+describe('parseSkillFile', () => {
+	it('extracts frontmatter and content separately', () => {
+		const content = `---
+name: research
+description: Research workflow
+---
+
+# Research Skill
+
+## When to Use
+Use when searching for papers.`
+
+		const result = parseSkillFile(content)
+		expect(result.ok).toBe(true)
+		if (result.ok) {
+			expect(result.value.frontmatter.name).toBe('research')
+			expect(result.value.frontmatter.description).toBe('Research workflow')
+			expect(result.value.content).toContain('# Research Skill')
+			expect(result.value.content).toContain('## When to Use')
+			// Content should not include frontmatter
+			expect(result.value.content).not.toContain('name:')
+		}
+	})
+
+	it('handles minimal content', () => {
+		const content = `---
+name: minimal
+description: Minimal skill
+---
+Just one line.`
+
+		const result = parseSkillFile(content)
+		expect(result.ok).toBe(true)
+		if (result.ok) {
+			expect(result.value.content).toBe('Just one line.')
+		}
+	})
+})
+
+// ============================================================================
+// discoverSkills tests
+// ============================================================================
+
+describe('discoverSkills', () => {
+	it('discovers skills from a directory', async () => {
+		// Create skill directories
+		const skillDir1 = path.join(TEST_DIR, 'research')
+		const skillDir2 = path.join(TEST_DIR, 'code-review')
+		await mkdir(skillDir1, { recursive: true })
+		await mkdir(skillDir2, { recursive: true })
+
+		await writeFile(
+			path.join(skillDir1, 'SKILL.md'),
+			`---
+name: research
+description: Research workflow
+---
+# Research content`,
+		)
+
+		await writeFile(
+			path.join(skillDir2, 'SKILL.md'),
+			`---
+name: code-review
+description: Code review process
+---
+# Code review content`,
+		)
+
+		const result = await discoverSkills(testFs, [TEST_DIR], '/')
+		expect(result.ok).toBe(true)
+		if (result.ok) {
+			expect(result.value).toHaveLength(2)
+			const names = result.value.map((s) => s.name)
+			expect(names).toContain('research')
+			expect(names).toContain('code-review')
+		}
+	})
+
+	it('skips directories without SKILL.md', async () => {
+		const skillDir = path.join(TEST_DIR, 'valid-skill')
+		const otherDir = path.join(TEST_DIR, 'not-a-skill')
+		await mkdir(skillDir, { recursive: true })
+		await mkdir(otherDir, { recursive: true })
+
+		await writeFile(
+			path.join(skillDir, 'SKILL.md'),
+			`---
+name: valid
+description: A valid skill
+---
+Content`,
+		)
+
+		await writeFile(path.join(otherDir, 'README.md'), 'Just a readme')
+
+		const result = await discoverSkills(testFs, [TEST_DIR], '/')
+		expect(result.ok).toBe(true)
+		if (result.ok) {
+			expect(result.value).toHaveLength(1)
+			expect(result.value[0].name).toBe('valid')
+		}
+	})
+
+	it('skips non-existent source directories', async () => {
+		const result = await discoverSkills(testFs, ['/nonexistent/path'], '/')
+		expect(result.ok).toBe(true)
+		if (result.ok) {
+			expect(result.value).toHaveLength(0)
+		}
+	})
+
+	it('resolves relative paths from basePath', async () => {
+		const baseDir = path.join(TEST_DIR, 'base')
+		const skillsDir = path.join(baseDir, 'skills')
+		const skillDir = path.join(skillsDir, 'my-skill')
+		await mkdir(skillDir, { recursive: true })
+
+		await writeFile(
+			path.join(skillDir, 'SKILL.md'),
+			`---
+name: my-skill
+description: A skill with relative path
+---
+Content`,
+		)
+
+		const result = await discoverSkills(testFs, ['skills'], baseDir)
+		expect(result.ok).toBe(true)
+		if (result.ok) {
+			expect(result.value).toHaveLength(1)
+			expect(result.value[0].name).toBe('my-skill')
+		}
+	})
+
+	it('fails on duplicate skill IDs', async () => {
+		const dir1 = path.join(TEST_DIR, 'skill1')
+		const dir2 = path.join(TEST_DIR, 'skill2')
+		await mkdir(dir1, { recursive: true })
+		await mkdir(dir2, { recursive: true })
+
+		// Both skills have the same name
+		await writeFile(
+			path.join(dir1, 'SKILL.md'),
+			`---
+name: duplicate
+description: First skill
+---
+Content 1`,
+		)
+
+		await writeFile(
+			path.join(dir2, 'SKILL.md'),
+			`---
+name: duplicate
+description: Second skill
+---
+Content 2`,
+		)
+
+		const result = await discoverSkills(testFs, [TEST_DIR], '/')
+		expect(result.ok).toBe(false)
+		if (!result.ok) {
+			expect(result.error.message).toContain('Duplicate skill ID')
+		}
+	})
+
+	it('fails on invalid frontmatter', async () => {
+		const skillDir = path.join(TEST_DIR, 'invalid-skill')
+		await mkdir(skillDir, { recursive: true })
+
+		await writeFile(
+			path.join(skillDir, 'SKILL.md'),
+			`---
+name: invalid
+# Missing description
+---
+Content`,
+		)
+
+		const result = await discoverSkills(testFs, [TEST_DIR], '/')
+		expect(result.ok).toBe(false)
+		if (!result.ok) {
+			expect(result.error.message).toContain('Failed to parse')
+		}
+	})
+
+	it('discovers skills from multiple source directories', async () => {
+		const dir1 = path.join(TEST_DIR, 'source1')
+		const dir2 = path.join(TEST_DIR, 'source2')
+		const skill1 = path.join(dir1, 'skill-a')
+		const skill2 = path.join(dir2, 'skill-b')
+		await mkdir(skill1, { recursive: true })
+		await mkdir(skill2, { recursive: true })
+
+		await writeFile(
+			path.join(skill1, 'SKILL.md'),
+			`---
+name: skill-a
+description: First source skill
+---
+Content A`,
+		)
+
+		await writeFile(
+			path.join(skill2, 'SKILL.md'),
+			`---
+name: skill-b
+description: Second source skill
+---
+Content B`,
+		)
+
+		const result = await discoverSkills(testFs, [dir1, dir2], '/')
+		expect(result.ok).toBe(true)
+		if (result.ok) {
+			expect(result.value).toHaveLength(2)
+		}
+	})
+})
+
+// ============================================================================
+// loadSkillContent tests
+// ============================================================================
+
+describe('loadSkillContent', () => {
+	it('loads skill content without frontmatter', async () => {
+		const skillDir = path.join(TEST_DIR, 'load-test')
+		await mkdir(skillDir, { recursive: true })
+
+		const skillPath = path.join(skillDir, 'SKILL.md')
+		await writeFile(
+			skillPath,
+			`---
+name: loadable
+description: A loadable skill
+---
+
+# Skill Instructions
+
+## Step 1
+Do something.
+
+## Step 2
+Do something else.`,
+		)
+
+		const result = await loadSkillContent(testFs, skillPath)
+		expect(result.ok).toBe(true)
+		if (result.ok) {
+			expect(result.value).toContain('# Skill Instructions')
+			expect(result.value).toContain('## Step 1')
+			expect(result.value).not.toContain('name: loadable')
+		}
+	})
+
+	it('fails for non-existent file', async () => {
+		const result = await loadSkillContent(testFs, '/nonexistent/SKILL.md')
+		expect(result.ok).toBe(false)
+		if (!result.ok) {
+			expect(result.error.message).toContain('not found')
+		}
+	})
+})

package/src/plugins/skills/discovery.ts

@@ -0,0 +1,276 @@
+/**
+ * Skill Discovery - Scans directories for SKILL.md files and parses frontmatter.
+ *
+ * Skills are discovered at preset load time. The system scans configured
+ * source directories for subdirectories containing SKILL.md files.
+ *
+ * Expected directory structure:
+ *   /skills/
+ *     research/
+ *       SKILL.md
+ *     code-review/
+ *       SKILL.md
+ *
+ * SKILL.md format:
+ *   ---
+ *   name: research
+ *   description: Structured research workflow
+ *   ---
+ *   # Research Skill
+ *   ...
+ */
+
+import * as path from 'node:path'
+import type { Result } from '~/lib/utils/result.js'
+import { Err, Ok } from '~/lib/utils/result.js'
+import type { FileSystem } from '~/platform/fs.js'
+import type { SkillMetadata } from '~/plugins/skills/schema.js'
+import { SkillId } from '~/plugins/skills/schema.js'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface SkillDiscoveryError {
+	type: 'discovery_error'
+	message: string
+	path?: string
+}
+
+export interface FrontmatterParseError {
+	type: 'frontmatter_error'
+	message: string
+}
+
+export interface ParsedFrontmatter {
+	name: string
+	description: string
+}
+
+export interface ParsedSkillFile {
+	frontmatter: ParsedFrontmatter
+	content: string
+}
+
+// ============================================================================
+// Frontmatter Parsing
+// ============================================================================
+
+/**
+ * Parse YAML frontmatter from a SKILL.md file content.
+ * Returns the parsed name and description fields.
+ *
+ * Expected format:
+ * ```
+ * ---
+ * name: skill-name
+ * description: Short description
+ * ---
+ * # Content follows...
+ * ```
+ */
+export function parseSkillFrontmatter(
+	content: string,
+): Result<ParsedFrontmatter, FrontmatterParseError> {
+	// Check for frontmatter delimiters
+	if (!content.startsWith('---')) {
+		return Err({
+			type: 'frontmatter_error',
+			message: 'SKILL.md must start with --- frontmatter delimiter',
+		})
+	}
+
+	// Find the closing delimiter
+	const endIndex = content.indexOf('---', 3)
+	if (endIndex === -1) {
+		return Err({
+			type: 'frontmatter_error',
+			message: 'Missing closing --- frontmatter delimiter',
+		})
+	}
+
+	const frontmatterBlock = content.slice(3, endIndex).trim()
+
+	// Simple YAML parsing for name and description fields
+	// Format: "key: value" on each line
+	const lines = frontmatterBlock.split('\n')
+	let name: string | undefined
+	let description: string | undefined
+
+	for (const line of lines) {
+		const trimmed = line.trim()
+		if (!trimmed || trimmed.startsWith('#')) continue
+
+		const colonIndex = trimmed.indexOf(':')
+		if (colonIndex === -1) continue
+
+		const key = trimmed.slice(0, colonIndex).trim()
+		let value = trimmed.slice(colonIndex + 1).trim()
+
+		// Remove surrounding quotes if present
+		if (
+			(value.startsWith('"') && value.endsWith('"'))
+			|| (value.startsWith("'") && value.endsWith("'"))
+		) {
+			value = value.slice(1, -1)
+		}
+
+		if (key === 'name') {
+			name = value
+		} else if (key === 'description') {
+			description = value
+		}
+	}
+
+	if (!name) {
+		return Err({
+			type: 'frontmatter_error',
+			message: 'Missing required "name" field in frontmatter',
+		})
+	}
+
+	if (!description) {
+		return Err({
+			type: 'frontmatter_error',
+			message: 'Missing required "description" field in frontmatter',
+		})
+	}
+
+	return Ok({ name, description })
+}
+
+/**
+ * Parse a SKILL.md file, extracting frontmatter and content separately.
+ */
+export function parseSkillFile(
+	fileContent: string,
+): Result<ParsedSkillFile, FrontmatterParseError> {
+	const frontmatterResult = parseSkillFrontmatter(fileContent)
+	if (!frontmatterResult.ok) {
+		return frontmatterResult
+	}
+
+	// Extract content after frontmatter
+	const endIndex = fileContent.indexOf('---', 3)
+	const content = fileContent.slice(endIndex + 3).trim()
+
+	return Ok({
+		frontmatter: frontmatterResult.value,
+		content,
+	})
+}
+
+// ============================================================================
+// Skill Discovery
+// ============================================================================
+
+/**
+ * Discover skills from configured source directories.
+ * Scans each source directory for subdirectories containing SKILL.md files.
+ */
+export async function discoverSkills(
+	fs: FileSystem,
+	sources: string[],
+	basePath: string,
+): Promise<Result<SkillMetadata[], SkillDiscoveryError>> {
+	const skills: SkillMetadata[] = []
+	const seenIds = new Set<string>()
+
+	for (const source of sources) {
+		// Resolve source path (relative to basePath or absolute)
+		const sourcePath = path.isAbsolute(source)
+			? source
+			: path.resolve(basePath, source)
+
+		// Check if source directory exists
+		if (!(await fs.exists(sourcePath))) {
+			// Skip non-existent directories (not an error)
+			continue
+		}
+
+		const stat = await fs.stat(sourcePath)
+		if (!stat.isDirectory()) {
+			return Err({
+				type: 'discovery_error',
+				message: `Skills source is not a directory`,
+				path: sourcePath,
+			})
+		}
+
+		// Scan for subdirectories containing SKILL.md
+		const entries = await fs.readdir(sourcePath, { withFileTypes: true })
+
+		for (const entry of entries) {
+			if (!entry.isDirectory()) continue
+
+			const skillDir = path.join(sourcePath, entry.name)
+			const skillFile = path.join(skillDir, 'SKILL.md')
+
+			if (!(await fs.exists(skillFile))) continue
+
+			// Read and parse the skill file
+			const content = await fs.readFile(skillFile, 'utf-8')
+			const parseResult = parseSkillFrontmatter(content)
+
+			if (!parseResult.ok) {
+				return Err({
+					type: 'discovery_error',
+					message: `Failed to parse ${skillFile}: ${parseResult.error.message}`,
+					path: skillFile,
+				})
+			}
+
+			const { name, description } = parseResult.value
+			const id = SkillId(name)
+
+			// Check for duplicate skill IDs
+			if (seenIds.has(id)) {
+				return Err({
+					type: 'discovery_error',
+					message: `Duplicate skill ID: ${id}`,
+					path: skillFile,
+				})
+			}
+			seenIds.add(id)
+
+			skills.push({
+				source: 'file',
+				id,
+				name,
+				description,
+				sourcePath: skillFile,
+			})
+		}
+	}
+
+	return Ok(skills)
+}
+
+/**
+ * Load the full content of a skill file (without frontmatter).
+ */
+export async function loadSkillContent(
+	fs: FileSystem,
+	skillPath: string,
+): Promise<Result<string, SkillDiscoveryError>> {
+	if (!(await fs.exists(skillPath))) {
+		return Err({
+			type: 'discovery_error',
+			message: 'Skill file not found',
+			path: skillPath,
+		})
+	}
+
+	const content = await fs.readFile(skillPath, 'utf-8')
+	const parseResult = parseSkillFile(content)
+
+	if (!parseResult.ok) {
+		return Err({
+			type: 'discovery_error',
+			message: parseResult.error.message,
+			path: skillPath,
+		})
+	}
+
+	return Ok(parseResult.value.content)
+}

package/src/plugins/skills/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Skills module - Skill discovery and loading.
+ */
+
+// Plugin
+export { skillsPlugin } from './plugin.js'
+export type {
+	PresetSkill,
+	SkillsAgentConfig,
+	SkillsPluginConfig as SkillsPresetConfig,
+	SkillsPluginContext,
+} from './plugin.js'
+
+// Schema
+export { SkillId, skillIdSchema } from './schema.js'
+export type { LoadedSkill, SkillMetadata } from './schema.js'
+
+// Events & state slice (now in plugin.ts)
+export { skillEvents } from './plugin.js'
+export type { SkillLoadedEvent } from './plugin.js'
+
+// Discovery (internal use)
+export {
+	discoverSkills,
+	type FrontmatterParseError,
+	loadSkillContent,
+	type ParsedFrontmatter,
+	type ParsedSkillFile,
+	parseSkillFile,
+	parseSkillFrontmatter,
+	type SkillDiscoveryError,
+} from './discovery.js'