@omnidev-ai/core 0.4.0 → 0.5.0

package/src/test-utils/mocks.ts

@@ -0,0 +1,101 @@
+/**
+ * Mock factories for creating test data
+ */
+
+export interface MockCapability {
+	id: string;
+	name: string;
+	version: string;
+	enabled?: boolean;
+	metadata?: Record<string, unknown>;
+}
+
+export interface MockConfig {
+	project: string;
+	capabilities: {
+		enable: string[];
+		disable?: string[];
+	};
+	profiles?: Record<string, unknown>;
+	env?: Record<string, string>;
+}
+
+export interface MockSkill {
+	id: string;
+	name: string;
+	description: string;
+	instructions: string;
+	triggers?: string[];
+}
+
+export interface MockRule {
+	id: string;
+	name: string;
+	content: string;
+	priority?: number;
+}
+
+/**
+ * Creates a mock capability with default values
+ * @param overrides - Partial capability object to override defaults
+ * @returns Mock capability object
+ */
+export function createMockCapability(overrides: Partial<MockCapability> = {}): MockCapability {
+	return {
+		id: "test-capability",
+		name: "Test Capability",
+		version: "1.0.0",
+		enabled: true,
+		metadata: {},
+		...overrides,
+	};
+}
+
+/**
+ * Creates a mock config with default values
+ * @param overrides - Partial config object to override defaults
+ * @returns Mock config object
+ */
+export function createMockConfig(overrides: Partial<MockConfig> = {}): MockConfig {
+	return {
+		project: "test-project",
+		capabilities: {
+			enable: [],
+			disable: [],
+		},
+		profiles: {},
+		env: {},
+		...overrides,
+	};
+}
+
+/**
+ * Creates a mock skill with default values
+ * @param overrides - Partial skill object to override defaults
+ * @returns Mock skill object
+ */
+export function createMockSkill(overrides: Partial<MockSkill> = {}): MockSkill {
+	return {
+		id: "test-skill",
+		name: "Test Skill",
+		description: "A test skill for unit testing",
+		instructions: "Test instructions",
+		triggers: [],
+		...overrides,
+	};
+}
+
+/**
+ * Creates a mock rule with default values
+ * @param overrides - Partial rule object to override defaults
+ * @returns Mock rule object
+ */
+export function createMockRule(overrides: Partial<MockRule> = {}): MockRule {
+	return {
+		id: "test-rule",
+		name: "Test Rule",
+		content: "# Test Rule\n\nTest rule content",
+		priority: 1,
+		...overrides,
+	};
+}

package/src/types/capability-export.ts

@@ -0,0 +1,157 @@
+/**
+ * Capability Export Types
+ *
+ * These types define the structure that capabilities use to export their features.
+ * Capabilities should import these types from @omnidev-ai/core and use them in their index.ts.
+ */
+
+/**
+ * File content structure for programmatic file creation
+ */
+export interface FileContent {
+	/** File name (relative path within capability) */
+	name: string;
+
+	/** File content */
+	content: string;
+}
+
+/**
+ * Documentation export structure
+ */
+export interface DocExport {
+	/** Document title */
+	title: string;
+
+	/** Markdown content */
+	content: string;
+}
+
+/**
+ * Skill export structure
+ */
+export interface SkillExport {
+	/** SKILL.md content (markdown with YAML frontmatter) */
+	skillMd: string;
+
+	/** Optional: Reference files to create (files the skill needs access to) */
+	references?: FileContent[];
+
+	/** Optional: Additional files to create (templates, examples, etc.) */
+	additionalFiles?: FileContent[];
+}
+
+/**
+ * Subagent export structure
+ *
+ * Defines a subagent that Claude can delegate tasks to.
+ * Uses YAML frontmatter in markdown format for configuration.
+ *
+ * @example
+ * ```typescript
+ * const codeReviewer: SubagentExport = {
+ *   subagentMd: `---
+ * name: code-reviewer
+ * description: Reviews code for quality and best practices
+ * tools: Read, Glob, Grep
+ * model: sonnet
+ * ---
+ *
+ * You are a code reviewer. When invoked, analyze the code and provide
+ * specific, actionable feedback on quality, security, and best practices.`
+ * };
+ * ```
+ */
+export interface SubagentExport {
+	/** SUBAGENT.md content (markdown with YAML frontmatter) */
+	subagentMd: string;
+}
+
+/**
+ * Slash command export structure
+ *
+ * Defines a slash command that can be invoked in Claude Code.
+ * Uses YAML frontmatter in markdown format for configuration.
+ *
+ * @example
+ * ```typescript
+ * const fixIssue: CommandExport = {
+ *   commandMd: `---
+ * name: fix-issue
+ * description: Fix a GitHub issue following coding standards
+ * allowed-tools: Bash(git add:*), Bash(git commit:*)
+ * ---
+ *
+ * Fix issue #$ARGUMENTS following our coding standards.
+ *
+ * 1. Read the issue details
+ * 2. Implement the fix
+ * 3. Write tests
+ * 4. Create a commit`
+ * };
+ * ```
+ */
+export interface CommandExport {
+	/** COMMAND.md content (markdown with YAML frontmatter) */
+	commandMd: string;
+}
+
+/**
+ * Complete capability export structure
+ *
+ * Capabilities export this as their default export from index.ts.
+ * All content fields are OPTIONAL and PROGRAMMATIC.
+ * Capabilities can also provide content via static files in their directory.
+ * Both approaches are supported and will be merged during sync.
+ *
+ * @example
+ * ```typescript
+ * // Static files approach - just export CLI commands
+ * export default {
+ *   cliCommands: { mycap: myRoutes },
+ *   gitignore: ["mycap/"],
+ *   sync
+ * } satisfies CapabilityExport;
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Programmatic approach - generate content dynamically
+ * export default {
+ *   cliCommands: { mycap: myRoutes },
+ *   docs: [{ title: "Guide", content: "# Guide\n..." }],
+ *   rules: ["# Rule content..."],
+ *   skills: [{ skillMd: "...", references: [...] }],
+ *   gitignore: ["mycap/"],
+ *   sync
+ * } satisfies CapabilityExport;
+ * ```
+ */
+export interface CapabilityExport {
+	/** CLI commands provided by this capability */
+	cliCommands?: Record<string, unknown>; // stricli Command type
+
+	/** Documentation (programmatic - optional, can also use docs/ directory) */
+	docs?: DocExport[];
+
+	/** Rules (programmatic - optional, can also use rules/ directory) */
+	rules?: string[]; // Array of markdown content strings
+
+	/** Skills (programmatic - optional, can also use skills/ directory) */
+	skills?: SkillExport[];
+
+	/** Subagents (programmatic - optional, can also use subagents/ directory) */
+	subagents?: SubagentExport[];
+
+	/** Commands (programmatic - optional, can also use commands/ directory) */
+	commands?: CommandExport[];
+
+	/** Gitignore patterns */
+	gitignore?: string[];
+
+	/** Custom sync hook function */
+	sync?: () => Promise<void>;
+
+	/** Additional exports for extensibility */
+	[key: string]: unknown;
+}

package/src/types/index.ts

@@ -0,0 +1,314 @@
+// Capability Export Types (for capability developers)
+export * from "./capability-export.js";
+
+// Capability Types
+export interface CapabilityMetadata {
+	id: string;
+	name: string;
+	version: string;
+	description: string;
+	/** Optional author information */
+	author?: {
+		name?: string;
+		email?: string;
+	};
+	/** Optional metadata about the capability author and source */
+	metadata?: {
+		author?: string;
+		repository?: string;
+		license?: string;
+		/** True if this capability was auto-generated by wrapping a skills repo */
+		wrapped?: boolean;
+		/** For wrapped capabilities: the full commit hash */
+		commit?: string;
+		/** True if this capability was auto-generated from omni.toml [mcps] section */
+		generated_from_omni_toml?: boolean;
+	};
+}
+
+export interface CapabilityExports {
+	module?: string;
+	gitignore?: string[];
+}
+
+export interface EnvDeclaration {
+	required?: boolean;
+	secret?: boolean;
+	default?: string;
+}
+
+export interface SyncConfig {
+	on_sync?: string;
+}
+
+export interface CliConfig {
+	commands?: string[];
+}
+
+export interface CapabilityConfig {
+	capability: CapabilityMetadata;
+	exports?: CapabilityExports;
+	env?: Record<string, EnvDeclaration | Record<string, never>>;
+	mcp?: McpConfig;
+	sync?: SyncConfig;
+	cli?: CliConfig;
+}
+
+export type McpTransport = "stdio" | "sse" | "http";
+
+export interface McpToolSchema {
+	name: string;
+	description: string;
+	inputSchema: Record<string, unknown>;
+}
+
+export interface McpConfig {
+	command: string;
+	args?: string[];
+	env?: Record<string, string>;
+	cwd?: string;
+	transport?: McpTransport;
+	tools?: McpToolSchema[];
+}
+
+// Content Types
+export interface Skill {
+	name: string;
+	description: string;
+	instructions: string;
+	capabilityId: string;
+}
+
+export interface Rule {
+	name: string;
+	content: string;
+	capabilityId: string;
+}
+
+export interface Doc {
+	name: string;
+	content: string;
+	capabilityId: string;
+}
+
+export type SubagentModel = "sonnet" | "opus" | "haiku" | "inherit";
+export type SubagentPermissionMode =
+	| "default"
+	| "acceptEdits"
+	| "dontAsk"
+	| "bypassPermissions"
+	| "plan";
+
+export interface SubagentHookConfig {
+	matcher?: string;
+	hooks: {
+		type: "command";
+		command: string;
+	}[];
+}
+
+export interface SubagentHooks {
+	PreToolUse?: SubagentHookConfig[];
+	PostToolUse?: SubagentHookConfig[];
+	Stop?: SubagentHookConfig[];
+}
+
+export interface Subagent {
+	/** Unique identifier using lowercase letters and hyphens */
+	name: string;
+	/** When Claude should delegate to this subagent */
+	description: string;
+	/** System prompt that guides the subagent's behavior */
+	systemPrompt: string;
+	/** Tools the subagent can use (inherits all if omitted) */
+	tools?: string[];
+	/** Tools to deny (removed from inherited or specified list) */
+	disallowedTools?: string[];
+	/** Model to use: sonnet, opus, haiku, or inherit */
+	model?: SubagentModel;
+	/** Permission mode for the subagent */
+	permissionMode?: SubagentPermissionMode;
+	/** Skills to load into the subagent's context at startup */
+	skills?: string[];
+	/** Lifecycle hooks scoped to this subagent */
+	hooks?: SubagentHooks;
+	/** Capability that provides this subagent */
+	capabilityId: string;
+}
+
+export interface Command {
+	/** Command name (used as /command-name) */
+	name: string;
+	/** Brief description of what this command does */
+	description: string;
+	/** Optional allowed tools specification (e.g., "Bash(git add:*), Bash(git status:*)") */
+	allowedTools?: string;
+	/** Command prompt (markdown content with support for $ARGUMENTS, $1, $2, !`commands`, @files) */
+	prompt: string;
+	/** Capability that provides this command */
+	capabilityId: string;
+}
+
+// Capability Source Types
+// Sources: local (manual), git (version via package.json)
+export type CapabilitySourceType = "local" | "git";
+
+/** Configuration for a Git-sourced capability */
+export interface GitCapabilitySourceConfig {
+	/** Source URL or shorthand (e.g., "github:user/repo", "git@github.com:...") */
+	source: string;
+	/** Git ref to checkout: tag, branch, or commit hash */
+	ref?: string;
+	/** Subdirectory within the repo containing the capability */
+	path?: string;
+}
+
+/** Combined type for all capability source configurations */
+export type CapabilitySourceConfig =
+	| string // shorthand: "github:user/repo"
+	| GitCapabilitySourceConfig;
+
+/** Lock file entry for a capability (version tracking) */
+export interface CapabilityLockEntry {
+	/** Original source reference */
+	source: string;
+	/** Version from capability.toml or package.json */
+	version: string;
+	/** For git sources: exact commit hash */
+	commit?: string;
+	/** Pinned ref if specified */
+	ref?: string;
+	/** Last update timestamp (ISO 8601) */
+	updated_at: string;
+}
+
+/** Lock file structure (omni.lock.toml at project root) */
+export interface CapabilitiesLockFile {
+	capabilities: Record<string, CapabilityLockEntry>;
+}
+
+/** Capabilities configuration section in omni.toml */
+export interface CapabilitiesConfig {
+	/** List of enabled capability IDs */
+	enable?: string[];
+	/** List of disabled capability IDs */
+	disable?: string[];
+	/** Capability sources: id -> source string or full config (git or file) */
+	sources?: Record<string, CapabilitySourceConfig>;
+}
+
+// Config Types
+export interface ProfileConfig {
+	capabilities?: string[];
+}
+
+export interface OmniConfig {
+	project?: string;
+	active_profile?: string;
+	always_enabled_capabilities?: string[];
+	env?: Record<string, string>;
+	profiles?: Record<string, ProfileConfig>;
+	providers?: {
+		enabled?: Provider[];
+	};
+	/** Capabilities configuration (enable/disable, sources) */
+	capabilities?: CapabilitiesConfig;
+	/** MCP server definitions that auto-generate capabilities */
+	mcps?: Record<string, McpConfig>;
+}
+
+// Provider Types
+export type Provider = "claude" | "codex" | "claude-code" | "cursor" | "opencode";
+
+export interface ProviderConfig {
+	provider?: Provider;
+	providers?: Provider[];
+}
+
+export function getActiveProviders(config: ProviderConfig): Provider[] {
+	if (config.providers) return config.providers;
+	if (config.provider) return [config.provider];
+	return ["claude"]; // Default
+}
+
+/** Runtime info about where a capability came from */
+export interface CapabilitySource {
+	type: CapabilitySourceType;
+	/** For git-sourced capabilities: the source URL/shorthand */
+	gitSource?: string;
+	/** For git-sourced capabilities: the pinned ref if any */
+	ref?: string;
+	/** For git-sourced capabilities: the current commit hash */
+	commit?: string;
+	/** Version from capability.toml or package.json */
+	version?: string;
+}
+
+// Loaded Capability
+export interface LoadedCapability {
+	id: string;
+	path: string;
+	config: CapabilityConfig;
+	skills: Skill[];
+	rules: Rule[];
+	docs: Doc[];
+	subagents: Subagent[];
+	commands: Command[];
+	typeDefinitions?: string;
+	gitignore?: string[];
+	exports: Record<string, unknown>;
+	/** Where this capability comes from */
+	source?: CapabilitySource;
+}
+
+// Adapter Types
+export type ProviderId = Provider | (string & {});
+
+export interface SyncBundle {
+	capabilities: LoadedCapability[];
+	skills: Skill[];
+	rules: Rule[];
+	docs: Doc[];
+	commands: Command[];
+	subagents: Subagent[];
+	instructionsPath: string; // usually .omni/instructions.md
+	instructionsContent: string; // generated by core
+}
+
+export interface ProviderContext {
+	projectRoot: string;
+	config: OmniConfig;
+	activeProfile?: string;
+}
+
+export interface ProviderInitResult {
+	// What did the init action do?
+	filesCreated?: string[];
+	message?: string;
+}
+
+export interface ProviderSyncResult {
+	// What did the sync action do?
+	filesWritten: string[];
+	filesDeleted: string[];
+}
+
+export interface ProviderManifest {
+	// State for cleanup
+	files: string[];
+	lastSync: string;
+}
+
+export interface ProviderAdapter {
+	id: ProviderId;
+	displayName: string;
+
+	// Optional: used by `omnidev init`
+	init?(ctx: ProviderContext): Promise<ProviderInitResult>;
+
+	// Main sync entrypoint
+	sync(bundle: SyncBundle, ctx: ProviderContext): Promise<ProviderSyncResult>;
+
+	// Optional cleanup hook (when provider removed or resources stale)
+	cleanup?(manifest: ProviderManifest, ctx: ProviderContext): Promise<void>;
+}