@omnidev-ai/core 0.4.0 → 0.5.1

package/src/capability/index.ts

@@ -0,0 +1,20 @@
+export { loadCommands } from "./commands";
+export { loadDocs } from "./docs";
+export { discoverCapabilities, loadCapability, loadCapabilityConfig } from "./loader";
+export type { CapabilityRegistry } from "./registry";
+export { buildCapabilityRegistry } from "./registry";
+export { loadRules, writeRules } from "./rules";
+export { loadSkills } from "./skills";
+export {
+	fetchAllCapabilitySources,
+	fetchCapabilitySource,
+	checkForUpdates,
+	loadLockFile,
+	saveLockFile,
+	parseSourceConfig,
+	sourceToGitUrl,
+	getSourceCapabilityPath,
+	getLockFilePath,
+} from "./sources";
+export type { FetchResult, SourceUpdateInfo, DiscoveredContent } from "./sources";
+export { loadSubagents } from "./subagents";

package/src/capability/loader.ts

@@ -0,0 +1,431 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { validateEnv } from "../config/env";
+import { parseCapabilityConfig } from "../config/parser";
+import type {
+	CapabilityConfig,
+	Command,
+	Doc,
+	LoadedCapability,
+	Rule,
+	Skill,
+	Subagent,
+} from "../types";
+import type {
+	CommandExport,
+	DocExport,
+	SkillExport,
+	SubagentExport,
+} from "../types/capability-export";
+import { loadCommands } from "./commands";
+import { loadDocs } from "./docs";
+import { loadRules } from "./rules";
+import { loadSkills } from "./skills";
+import { loadSubagents } from "./subagents";
+
+const CAPABILITIES_DIR = ".omni/capabilities";
+
+/**
+ * Discovers capabilities by scanning the .omni/capabilities directory.
+ * A directory is considered a capability if it contains a capability.toml file.
+ *
+ * @returns Array of capability directory paths
+ */
+export async function discoverCapabilities(): Promise<string[]> {
+	const capabilities: string[] = [];
+
+	if (existsSync(CAPABILITIES_DIR)) {
+		const entries = readdirSync(CAPABILITIES_DIR, { withFileTypes: true }).sort((a, b) =>
+			a.name.localeCompare(b.name),
+		);
+
+		for (const entry of entries) {
+			if (entry.isDirectory()) {
+				const entryPath = join(CAPABILITIES_DIR, entry.name);
+				const configPath = join(entryPath, "capability.toml");
+				if (existsSync(configPath)) {
+					capabilities.push(entryPath);
+				}
+			}
+		}
+	}
+
+	return capabilities;
+}
+
+/**
+ * Loads and parses a capability configuration file.
+ * Validates required fields.
+ *
+ * @param capabilityPath - Path to the capability directory
+ * @returns Parsed capability configuration
+ * @throws Error if the config is invalid
+ */
+export async function loadCapabilityConfig(capabilityPath: string): Promise<CapabilityConfig> {
+	const configPath = join(capabilityPath, "capability.toml");
+	const content = await Bun.file(configPath).text();
+	const config = parseCapabilityConfig(content);
+
+	return config;
+}
+
+/**
+ * Dynamically imports capability exports from index.ts.
+ * Returns an empty object if index.ts doesn't exist.
+ *
+ * @param capabilityPath - Path to the capability directory
+ * @returns Exported module or empty object
+ * @throws Error if import fails
+ */
+async function importCapabilityExports(capabilityPath: string): Promise<Record<string, unknown>> {
+	const indexPath = join(capabilityPath, "index.ts");
+
+	if (!existsSync(indexPath)) {
+		return {};
+	}
+
+	try {
+		const absolutePath = join(process.cwd(), indexPath);
+		const module = await import(absolutePath);
+		return module;
+	} catch (error) {
+		// Check if it's a module resolution error
+		const errorMessage = String(error);
+		if (errorMessage.includes("Cannot find module")) {
+			const match = errorMessage.match(/Cannot find module '([^']+)'/);
+			const missingModule = match ? match[1] : "unknown";
+			throw new Error(
+				`Missing dependency '${missingModule}' for capability at ${capabilityPath}.\n` +
+					`If this is a project-specific capability, install dependencies or remove it from .omni/capabilities/`,
+			);
+		}
+		throw new Error(`Failed to import capability at ${capabilityPath}: ${error}`);
+	}
+}
+
+/**
+ * Loads type definitions from types.d.ts if it exists.
+ *
+ * @param capabilityPath - Path to the capability directory
+ * @returns Type definitions as string or undefined
+ */
+async function loadTypeDefinitions(capabilityPath: string): Promise<string | undefined> {
+	const typesPath = join(capabilityPath, "types.d.ts");
+
+	if (!existsSync(typesPath)) {
+		return undefined;
+	}
+
+	return Bun.file(typesPath).text();
+}
+
+/**
+ * Convert programmatic skill exports to Skill objects
+ * Expects SkillExport format with skillMd (markdown with YAML frontmatter)
+ */
+function convertSkillExports(skillExports: unknown[], capabilityId: string): Skill[] {
+	return skillExports.map((skillExport) => {
+		const exportObj = skillExport as SkillExport;
+		const lines = exportObj.skillMd.split("\n");
+		let name = "unnamed";
+		let description = "";
+		let instructions = exportObj.skillMd;
+
+		// Simple YAML frontmatter parser
+		if (lines[0]?.trim() === "---") {
+			const endIndex = lines.findIndex((line, i) => i > 0 && line.trim() === "---");
+			if (endIndex > 0) {
+				const frontmatter = lines.slice(1, endIndex);
+				instructions = lines
+					.slice(endIndex + 1)
+					.join("\n")
+					.trim();
+
+				for (const line of frontmatter) {
+					const match = line.match(/^(\w+):\s*(.+)$/);
+					if (match?.[1] && match[2]) {
+						const key = match[1];
+						const value = match[2];
+						if (key === "name") {
+							name = value.replace(/^["']|["']$/g, "");
+						} else if (key === "description") {
+							description = value.replace(/^["']|["']$/g, "");
+						}
+					}
+				}
+			}
+		}
+
+		return {
+			name,
+			description,
+			instructions,
+			capabilityId,
+		};
+	});
+}
+
+/**
+ * Convert programmatic rule exports to Rule objects
+ * Expects array of string content (markdown)
+ */
+function convertRuleExports(ruleExports: unknown[], capabilityId: string): Rule[] {
+	return ruleExports.map((ruleExport, index) => {
+		return {
+			name: `rule-${index + 1}`,
+			content: String(ruleExport).trim(),
+			capabilityId,
+		};
+	});
+}
+
+/**
+ * Convert programmatic doc exports to Doc objects
+ * Expects DocExport format with title and content
+ */
+function convertDocExports(docExports: unknown[], capabilityId: string): Doc[] {
+	return docExports.map((docExport) => {
+		const exportObj = docExport as DocExport;
+		return {
+			name: exportObj.title,
+			content: exportObj.content.trim(),
+			capabilityId,
+		};
+	});
+}
+
+/**
+ * Convert programmatic subagent exports to Subagent objects
+ * Parses SubagentExport markdown with YAML frontmatter
+ */
+function convertSubagentExports(subagentExports: unknown[], capabilityId: string): Subagent[] {
+	return subagentExports.map((subagentExport) => {
+		const exportObj = subagentExport as SubagentExport;
+		const lines = exportObj.subagentMd.split("\n");
+		let name = "unnamed";
+		let description = "";
+		let systemPrompt = exportObj.subagentMd;
+		let tools: string[] | undefined;
+		let disallowedTools: string[] | undefined;
+		let model: string | undefined;
+		let permissionMode: string | undefined;
+		let skills: string[] | undefined;
+
+		// Simple YAML frontmatter parser
+		if (lines[0]?.trim() === "---") {
+			const endIndex = lines.findIndex((line, i) => i > 0 && line.trim() === "---");
+			if (endIndex > 0) {
+				const frontmatter = lines.slice(1, endIndex);
+				systemPrompt = lines
+					.slice(endIndex + 1)
+					.join("\n")
+					.trim();
+
+				for (const line of frontmatter) {
+					const match = line.match(/^(\w+):\s*(.+)$/);
+					if (match?.[1] && match[2]) {
+						const key = match[1];
+						const value = match[2].replace(/^["']|["']$/g, "");
+						switch (key) {
+							case "name":
+								name = value;
+								break;
+							case "description":
+								description = value;
+								break;
+							case "tools":
+								tools = value.split(",").map((t) => t.trim());
+								break;
+							case "disallowedTools":
+								disallowedTools = value.split(",").map((t) => t.trim());
+								break;
+							case "model":
+								model = value;
+								break;
+							case "permissionMode":
+								permissionMode = value;
+								break;
+							case "skills":
+								skills = value.split(",").map((s) => s.trim());
+								break;
+						}
+					}
+				}
+			}
+		}
+
+		const result: Subagent = {
+			name,
+			description,
+			systemPrompt,
+			capabilityId,
+		};
+
+		if (tools) result.tools = tools;
+		if (disallowedTools) result.disallowedTools = disallowedTools;
+		if (model) {
+			result.model = model as NonNullable<Subagent["model"]>;
+		}
+		if (permissionMode) {
+			result.permissionMode = permissionMode as NonNullable<Subagent["permissionMode"]>;
+		}
+		if (skills) result.skills = skills;
+
+		return result;
+	});
+}
+
+/**
+ * Convert programmatic command exports to Command objects
+ * Parses CommandExport markdown with YAML frontmatter
+ */
+function convertCommandExports(commandExports: unknown[], capabilityId: string): Command[] {
+	return commandExports.map((commandExport) => {
+		const exportObj = commandExport as CommandExport;
+		const lines = exportObj.commandMd.split("\n");
+		let name = "unnamed";
+		let description = "";
+		let prompt = exportObj.commandMd;
+		let allowedTools: string | undefined;
+
+		// Simple YAML frontmatter parser
+		if (lines[0]?.trim() === "---") {
+			const endIndex = lines.findIndex((line, i) => i > 0 && line.trim() === "---");
+			if (endIndex > 0) {
+				const frontmatter = lines.slice(1, endIndex);
+				prompt = lines
+					.slice(endIndex + 1)
+					.join("\n")
+					.trim();
+
+				for (const line of frontmatter) {
+					const match = line.match(/^(\w+):\s*(.+)$/);
+					if (match?.[1] && match[2]) {
+						const key = match[1];
+						const value = match[2].replace(/^["']|["']$/g, "");
+						switch (key) {
+							case "name":
+								name = value;
+								break;
+							case "description":
+								description = value;
+								break;
+							case "allowedTools":
+							case "allowed-tools":
+								allowedTools = value;
+								break;
+						}
+					}
+				}
+			}
+		}
+
+		const result: Command = {
+			name,
+			description,
+			prompt,
+			capabilityId,
+		};
+
+		if (allowedTools) {
+			result.allowedTools = allowedTools;
+		}
+
+		return result;
+	});
+}
+
+/**
+ * Loads a complete capability including config, skills, rules, docs, and exports.
+ * Validates environment requirements before loading.
+ *
+ * @param capabilityPath - Path to the capability directory
+ * @param env - Environment variables to validate against
+ * @returns Fully loaded capability
+ * @throws Error if validation fails or loading errors occur
+ */
+export async function loadCapability(
+	capabilityPath: string,
+	env: Record<string, string>,
+): Promise<LoadedCapability> {
+	const config = await loadCapabilityConfig(capabilityPath);
+	const id = config.capability.id;
+
+	// Validate environment
+	if (config.env) {
+		validateEnv(config.env, env, id);
+	}
+
+	// Load content - programmatic takes precedence
+	const exports = await importCapabilityExports(capabilityPath);
+
+	// Check if exports contains programmatic skills/rules/docs
+	// biome-ignore lint/suspicious/noExplicitAny: Dynamic module exports need runtime type checking
+	const exportsAny = exports as any;
+
+	const skills =
+		"skills" in exports && Array.isArray(exportsAny.skills)
+			? convertSkillExports(exportsAny.skills, id)
+			: await loadSkills(capabilityPath, id);
+
+	const rules =
+		"rules" in exports && Array.isArray(exportsAny.rules)
+			? convertRuleExports(exportsAny.rules, id)
+			: await loadRules(capabilityPath, id);
+
+	const docs =
+		"docs" in exports && Array.isArray(exportsAny.docs)
+			? convertDocExports(exportsAny.docs, id)
+			: await loadDocs(capabilityPath, id);
+
+	const subagents =
+		"subagents" in exports && Array.isArray(exportsAny.subagents)
+			? convertSubagentExports(exportsAny.subagents, id)
+			: await loadSubagents(capabilityPath, id);
+
+	const commands =
+		"commands" in exports && Array.isArray(exportsAny.commands)
+			? convertCommandExports(exportsAny.commands, id)
+			: await loadCommands(capabilityPath, id);
+
+	const typeDefinitionsFromExports =
+		"typeDefinitions" in exports && typeof exportsAny.typeDefinitions === "string"
+			? (exportsAny.typeDefinitions as string)
+			: undefined;
+
+	const typeDefinitions =
+		typeDefinitionsFromExports !== undefined
+			? typeDefinitionsFromExports
+			: await loadTypeDefinitions(capabilityPath);
+
+	// Extract gitignore patterns from exports
+	const gitignore =
+		"gitignore" in exports && Array.isArray(exportsAny.gitignore)
+			? (exportsAny.gitignore as string[])
+			: undefined;
+
+	// Build result object with explicit handling for optional typeDefinitions
+	const result: LoadedCapability = {
+		id,
+		path: capabilityPath,
+		config,
+		skills,
+		rules,
+		docs,
+		subagents,
+		commands,
+		exports,
+	};
+
+	// Only add typeDefinitions if it exists
+	if (typeDefinitions !== undefined) {
+		result.typeDefinitions = typeDefinitions;
+	}
+
+	// Only add gitignore if it exists
+	if (gitignore !== undefined) {
+		result.gitignore = gitignore;
+	}
+
+	return result;
+}

package/src/capability/registry.ts

@@ -0,0 +1,55 @@
+import { getEnabledCapabilities } from "../config/capabilities";
+import { loadEnvironment } from "../config/env";
+import type { Doc, LoadedCapability, Rule, Skill } from "../types";
+import { discoverCapabilities, loadCapability } from "./loader";
+
+/**
+ * Registry of loaded capabilities with helper functions.
+ */
+export interface CapabilityRegistry {
+	capabilities: Map<string, LoadedCapability>;
+	getCapability(id: string): LoadedCapability | undefined;
+	getAllCapabilities(): LoadedCapability[];
+	getAllSkills(): Skill[];
+	getAllRules(): Rule[];
+	getAllDocs(): Doc[];
+}
+
+/**
+ * Builds a capability registry by discovering, loading, and filtering capabilities.
+ * Only enabled capabilities (based on active profile) are included.
+ *
+ * @returns Capability registry with helper functions
+ */
+export async function buildCapabilityRegistry(): Promise<CapabilityRegistry> {
+	const env = await loadEnvironment();
+	const enabledIds = await getEnabledCapabilities();
+
+	const capabilityPaths = await discoverCapabilities();
+	const capabilities = new Map<string, LoadedCapability>();
+
+	for (const path of capabilityPaths) {
+		try {
+			const cap = await loadCapability(path, env);
+
+			// Only add if enabled
+			if (enabledIds.includes(cap.id)) {
+				capabilities.set(cap.id, cap);
+			}
+		} catch (error) {
+			// Extract just the error message without stack trace for cleaner output
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			console.warn(`Warning: Skipping capability at ${path}`);
+			console.warn(`  ${errorMessage}`);
+		}
+	}
+
+	return {
+		capabilities,
+		getCapability: (id: string) => capabilities.get(id),
+		getAllCapabilities: () => [...capabilities.values()],
+		getAllSkills: () => [...capabilities.values()].flatMap((c) => c.skills),
+		getAllRules: () => [...capabilities.values()].flatMap((c) => c.rules),
+		getAllDocs: () => [...capabilities.values()].flatMap((c) => c.docs),
+	};
+}

package/src/capability/rules.ts

@@ -0,0 +1,135 @@
+import { existsSync, readdirSync } from "node:fs";
+import { basename, join } from "node:path";
+import type { Doc, Rule } from "../types";
+
+/**
+ * Load rules from a capability's rules/ directory
+ * @param capabilityPath Path to the capability directory
+ * @param capabilityId ID of the capability
+ * @returns Array of Rule objects
+ */
+export async function loadRules(capabilityPath: string, capabilityId: string): Promise<Rule[]> {
+	const rulesDir = join(capabilityPath, "rules");
+
+	if (!existsSync(rulesDir)) {
+		return [];
+	}
+
+	const rules: Rule[] = [];
+	const entries = readdirSync(rulesDir, { withFileTypes: true }).sort((a, b) =>
+		a.name.localeCompare(b.name),
+	);
+
+	for (const entry of entries) {
+		if (entry.isFile() && entry.name.endsWith(".md")) {
+			const rulePath = join(rulesDir, entry.name);
+			const content = await Bun.file(rulePath).text();
+
+			rules.push({
+				name: basename(entry.name, ".md"),
+				content: content.trim(),
+				capabilityId,
+			});
+		}
+	}
+
+	return rules;
+}
+
+/**
+ * Write aggregated rules and docs to .omni/instructions.md
+ * Updates the generated section between markers while preserving user content
+ * @param rules Array of rules from all enabled capabilities
+ * @param docs Array of docs from all enabled capabilities
+ */
+export async function writeRules(rules: Rule[], docs: Doc[] = []): Promise<void> {
+	const instructionsPath = ".omni/instructions.md";
+
+	// Generate content from rules and docs
+	const rulesContent = generateRulesContent(rules, docs);
+
+	// Read existing content or create new file
+	let content: string;
+	if (existsSync(instructionsPath)) {
+		content = await Bun.file(instructionsPath).text();
+	} else {
+		// Create new file with basic template
+		content = `# OmniDev Instructions
+
+## Project Description
+<!-- TODO: Add 2-3 sentences describing your project -->
+[Describe what this project does and its main purpose]
+
+<!-- BEGIN OMNIDEV GENERATED CONTENT - DO NOT EDIT BELOW THIS LINE -->
+<!-- END OMNIDEV GENERATED CONTENT -->
+`;
+	}
+
+	// Replace content between markers
+	const beginMarker = "<!-- BEGIN OMNIDEV GENERATED CONTENT - DO NOT EDIT BELOW THIS LINE -->";
+	const endMarker = "<!-- END OMNIDEV GENERATED CONTENT -->";
+
+	const beginIndex = content.indexOf(beginMarker);
+	const endIndex = content.indexOf(endMarker);
+
+	if (beginIndex === -1 || endIndex === -1) {
+		// Markers not found, append to end
+		content += `\n\n${beginMarker}\n${rulesContent}\n${endMarker}\n`;
+	} else {
+		// Replace content between markers
+		content =
+			content.substring(0, beginIndex + beginMarker.length) +
+			"\n" +
+			rulesContent +
+			"\n" +
+			content.substring(endIndex);
+	}
+
+	await Bun.write(instructionsPath, content);
+}
+
+function generateRulesContent(rules: Rule[], docs: Doc[] = []): string {
+	if (rules.length === 0 && docs.length === 0) {
+		return `<!-- This section is automatically updated when capabilities change -->
+
+## Capabilities
+
+No capabilities enabled yet. Run \`omnidev capability enable <name>\` to enable capabilities.`;
+	}
+
+	let content = `<!-- This section is automatically updated when capabilities change -->
+
+## Capabilities
+
+`;
+
+	// Add documentation section if there are docs
+	if (docs.length > 0) {
+		content += `### Documentation
+
+`;
+		for (const doc of docs) {
+			content += `#### ${doc.name} (from ${doc.capabilityId})
+
+${doc.content}
+
+`;
+		}
+	}
+
+	// Add rules section if there are rules
+	if (rules.length > 0) {
+		content += `### Rules
+
+`;
+		for (const rule of rules) {
+			content += `#### ${rule.name} (from ${rule.capabilityId})
+
+${rule.content}
+
+`;
+		}
+	}
+
+	return content.trim();
+}

package/src/capability/skills.ts

@@ -0,0 +1,58 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import type { Skill } from "../types";
+import { parseFrontmatterWithMarkdown } from "./yaml-parser";
+
+interface SkillFrontmatter {
+	name: string;
+	description: string;
+}
+
+export async function loadSkills(capabilityPath: string, capabilityId: string): Promise<Skill[]> {
+	const skillsDir = join(capabilityPath, "skills");
+
+	if (!existsSync(skillsDir)) {
+		return [];
+	}
+
+	const skills: Skill[] = [];
+	const entries = readdirSync(skillsDir, { withFileTypes: true }).sort((a, b) =>
+		a.name.localeCompare(b.name),
+	);
+
+	for (const entry of entries) {
+		if (entry.isDirectory()) {
+			const skillPath = join(skillsDir, entry.name, "SKILL.md");
+			if (existsSync(skillPath)) {
+				const skill = await parseSkillFile(skillPath, capabilityId);
+				skills.push(skill);
+			}
+		}
+	}
+
+	return skills;
+}
+
+async function parseSkillFile(filePath: string, capabilityId: string): Promise<Skill> {
+	const content = await Bun.file(filePath).text();
+
+	const parsed = parseFrontmatterWithMarkdown<SkillFrontmatter>(content);
+
+	if (!parsed) {
+		throw new Error(`Invalid SKILL.md format at ${filePath}: missing YAML frontmatter`);
+	}
+
+	const frontmatter = parsed.frontmatter;
+	const instructions = parsed.markdown;
+
+	if (!frontmatter.name || !frontmatter.description) {
+		throw new Error(`Invalid SKILL.md at ${filePath}: name and description required`);
+	}
+
+	return {
+		name: frontmatter.name,
+		description: frontmatter.description,
+		instructions: instructions.trim(),
+		capabilityId,
+	};
+}