@omnidev-ai/core 0.4.0 → 0.5.0

package/src/sync.ts

@@ -0,0 +1,288 @@
+import { spawn } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import { buildCapabilityRegistry } from "./capability/registry";
+import { writeRules } from "./capability/rules";
+import { fetchAllCapabilitySources } from "./capability/sources";
+import { loadConfig } from "./config/loader";
+import { syncMcpJson } from "./mcp-json/manager";
+import {
+	buildManifestFromCapabilities,
+	cleanupStaleResources,
+	loadManifest,
+	saveManifest,
+} from "./state/manifest";
+import type { ProviderAdapter, ProviderContext, SyncBundle } from "./types";
+
+export interface SyncResult {
+	capabilities: string[];
+	skillCount: number;
+	ruleCount: number;
+	docCount: number;
+}
+
+export interface SyncOptions {
+	silent?: boolean;
+	/** Optional list of adapters to run. If not provided, adapters are not run. */
+	adapters?: ProviderAdapter[];
+}
+
+/**
+ * Install dependencies for capabilities in .omni/capabilities/
+ * Only installs for capabilities that have a package.json
+ */
+export async function installCapabilityDependencies(silent: boolean): Promise<void> {
+	const { existsSync, readdirSync } = await import("node:fs");
+	const { join } = await import("node:path");
+
+	const capabilitiesDir = ".omni/capabilities";
+
+	// Check if .omni/capabilities exists
+	if (!existsSync(capabilitiesDir)) {
+		return; // Nothing to install
+	}
+
+	const entries = readdirSync(capabilitiesDir, { withFileTypes: true });
+
+	for (const entry of entries) {
+		if (!entry.isDirectory()) {
+			continue;
+		}
+
+		const capabilityPath = join(capabilitiesDir, entry.name);
+		const packageJsonPath = join(capabilityPath, "package.json");
+
+		// Skip if no package.json
+		if (!existsSync(packageJsonPath)) {
+			continue;
+		}
+
+		if (!silent) {
+			console.log(`Installing dependencies for ${capabilityPath}...`);
+		}
+
+		// Run bun install in the capability directory
+		await new Promise<void>((resolve, reject) => {
+			const proc = spawn("bun", ["install"], {
+				cwd: capabilityPath,
+				stdio: silent ? "ignore" : "inherit",
+			});
+
+			proc.on("close", (code) => {
+				if (code === 0) {
+					resolve();
+				} else {
+					reject(new Error(`Failed to install dependencies for ${capabilityPath}`));
+				}
+			});
+
+			proc.on("error", (error) => {
+				reject(error);
+			});
+		});
+	}
+}
+
+/**
+ * Build a provider-agnostic SyncBundle from the capability registry.
+ * This bundle can then be passed to adapters for provider-specific materialization.
+ */
+export async function buildSyncBundle(options?: {
+	silent?: boolean;
+}): Promise<{ bundle: SyncBundle }> {
+	const silent = options?.silent ?? false;
+
+	// Fetch capability sources from git repos FIRST (before discovery)
+	const config = await loadConfig();
+	await fetchAllCapabilitySources(config, { silent });
+
+	// Install capability dependencies before building registry
+	await installCapabilityDependencies(silent);
+
+	// Build registry
+	const registry = await buildCapabilityRegistry();
+	const capabilities = registry.getAllCapabilities();
+	const skills = registry.getAllSkills();
+	const rules = registry.getAllRules();
+	const docs = registry.getAllDocs();
+	const commands = capabilities.flatMap((c) => c.commands);
+	const subagents = capabilities.flatMap((c) => c.subagents);
+
+	// Generate instructions content
+	const instructionsContent = generateInstructionsContent(rules, docs);
+
+	const bundle: SyncBundle = {
+		capabilities,
+		skills,
+		rules,
+		docs,
+		commands,
+		subagents,
+		instructionsPath: ".omni/instructions.md",
+		instructionsContent,
+	};
+
+	return { bundle };
+}
+
+/**
+ * Central sync function that regenerates all agent configuration files.
+ * Called automatically after any config change (init, capability enable/disable, profile change).
+ *
+ * If adapters are provided, they will be called after core sync to write provider-specific files.
+ */
+export async function syncAgentConfiguration(options?: SyncOptions): Promise<SyncResult> {
+	const silent = options?.silent ?? false;
+	const adapters = options?.adapters ?? [];
+
+	if (!silent) {
+		console.log("Syncing agent configuration...");
+	}
+
+	const { bundle } = await buildSyncBundle({ silent });
+	const capabilities = bundle.capabilities;
+
+	// Load previous manifest and cleanup stale resources from disabled capabilities
+	const previousManifest = await loadManifest();
+	const currentCapabilityIds = new Set(capabilities.map((c) => c.id));
+
+	const cleanupResult = await cleanupStaleResources(previousManifest, currentCapabilityIds);
+
+	if (
+		!silent &&
+		(cleanupResult.deletedSkills.length > 0 || cleanupResult.deletedRules.length > 0)
+	) {
+		console.log("Cleaned up stale resources:");
+		if (cleanupResult.deletedSkills.length > 0) {
+			console.log(
+				`  - Removed ${cleanupResult.deletedSkills.length} skill(s): ${cleanupResult.deletedSkills.join(", ")}`,
+			);
+		}
+		if (cleanupResult.deletedRules.length > 0) {
+			console.log(
+				`  - Removed ${cleanupResult.deletedRules.length} rule(s): ${cleanupResult.deletedRules.join(", ")}`,
+			);
+		}
+	}
+
+	// Call sync hooks for capabilities that have them
+	for (const capability of capabilities) {
+		// Check for structured export sync function first (new approach)
+		// biome-ignore lint/suspicious/noExplicitAny: Dynamic module exports need runtime type checking
+		const defaultExport = (capability.exports as any).default;
+		if (defaultExport && typeof defaultExport.sync === "function") {
+			try {
+				await defaultExport.sync();
+			} catch (error) {
+				console.error(`Error running sync hook for ${capability.id}:`, error);
+			}
+		}
+		// Fall back to TOML-based sync hook (legacy approach)
+		else if (capability.config.sync?.on_sync) {
+			const syncFnName = capability.config.sync.on_sync;
+			const syncFn = capability.exports[syncFnName];
+
+			if (typeof syncFn === "function") {
+				try {
+					await syncFn();
+				} catch (error) {
+					console.error(`Error running sync hook for ${capability.id}:`, error);
+				}
+			}
+		}
+	}
+
+	// Ensure core directories exist
+	mkdirSync(".omni", { recursive: true });
+
+	// Write rules and docs to .omni/instructions.md (provider-agnostic)
+	await writeRules(bundle.rules, bundle.docs);
+
+	// Sync .mcp.json with capability MCP servers (before saving manifest)
+	await syncMcpJson(capabilities, previousManifest, { silent });
+
+	// Save updated manifest for future cleanup
+	const newManifest = buildManifestFromCapabilities(capabilities);
+	await saveManifest(newManifest);
+
+	// Run enabled adapters to write provider-specific files
+	if (adapters.length > 0) {
+		const config = await loadConfig();
+		const ctx: ProviderContext = {
+			projectRoot: process.cwd(),
+			config,
+		};
+
+		for (const adapter of adapters) {
+			try {
+				const result = await adapter.sync(bundle, ctx);
+				if (!silent && result.filesWritten.length > 0) {
+					console.log(`  - ${adapter.displayName}: ${result.filesWritten.length} files`);
+				}
+			} catch (error) {
+				console.error(`Error running ${adapter.displayName} adapter:`, error);
+			}
+		}
+	}
+
+	if (!silent) {
+		console.log("✓ Synced:");
+		console.log(
+			`  - .omni/instructions.md (${bundle.docs.length} docs, ${bundle.rules.length} rules)`,
+		);
+		if (adapters.length > 0) {
+			console.log(`  - Provider adapters: ${adapters.map((a) => a.displayName).join(", ")}`);
+		}
+	}
+
+	return {
+		capabilities: capabilities.map((c) => c.id),
+		skillCount: bundle.skills.length,
+		ruleCount: bundle.rules.length,
+		docCount: bundle.docs.length,
+	};
+}
+
+/**
+ * Generate instructions.md content from rules and docs.
+ */
+function generateInstructionsContent(rules: SyncBundle["rules"], docs: SyncBundle["docs"]): string {
+	if (rules.length === 0 && docs.length === 0) {
+		return `## Capabilities
+
+No capabilities enabled yet. Run \`omnidev capability enable <name>\` to enable capabilities.`;
+	}
+
+	let content = `## 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/templates/agents.ts

@@ -0,0 +1,14 @@
+/**
+ * Template for AGENTS.md (Codex provider)
+ * Creates a minimal file with reference to OmniDev instructions
+ */
+export function generateAgentsTemplate(): string {
+	return `# Project Instructions
+
+<!-- Add your project-specific instructions here -->
+
+## OmniDev
+
+@import .omni/instructions.md
+`;
+}

package/src/templates/claude.ts

@@ -0,0 +1,57 @@
+/**
+ * Template for CLAUDE.md (Claude provider)
+ * Creates a minimal file with reference to OmniDev instructions
+ */
+export function generateClaudeTemplate(): string {
+	return `# Project Instructions
+
+<!-- Add your project-specific instructions here -->
+
+## OmniDev
+
+@import .omni/instructions.md
+`;
+}
+
+/**
+ * Template for .omni/instructions.md
+ * Contains OmniDev-specific instructions and capability rules
+ */
+export function generateInstructionsTemplate(): string {
+	return `# OmniDev Instructions
+
+## Project Description
+<!-- TODO: Add 2-3 sentences describing your project -->
+[Describe what this project does and its main purpose]
+
+## How OmniDev Works
+
+OmniDev manages capability content for your project. Capabilities can provide:
+
+- Skills (for agent workflows)
+- Rules (for guardrails and conventions)
+- Docs (reference material)
+- Commands and subagents (optional)
+
+Enable capabilities with:
+
+\`\`\`
+omnidev capability enable <capability-id>
+\`\`\`
+
+OmniDev will automatically sync enabled capabilities into your workspace. If you want to force a refresh:
+
+\`\`\`
+omnidev sync
+\`\`\`
+
+<!-- BEGIN OMNIDEV GENERATED CONTENT - DO NOT EDIT BELOW THIS LINE -->
+<!-- This section is automatically updated by 'omnidev agents sync' -->
+
+## Capabilities
+
+No capabilities enabled yet. Run \`omnidev capability enable <name>\` to enable capabilities.
+
+<!-- END OMNIDEV GENERATED CONTENT -->
+`;
+}

package/src/test-utils/helpers.ts

@@ -0,0 +1,289 @@
+/**
+ * Helper functions for testing
+ */
+
+import { afterEach, beforeEach, expect } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir as osTmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Expects an async function to throw an error
+ * @param fn - Async function that should throw
+ * @param errorMatch - Optional string or regex to match against error message
+ * @throws If the function doesn't throw
+ */
+export async function expectToThrowAsync(
+	fn: () => Promise<unknown>,
+	errorMatch?: string | RegExp,
+): Promise<void> {
+	let threw = false;
+	let caughtError: Error | undefined;
+
+	try {
+		await fn();
+	} catch (e) {
+		threw = true;
+		caughtError = e as Error;
+	}
+
+	expect(threw).toBe(true);
+
+	if (errorMatch && caughtError) {
+		if (typeof errorMatch === "string") {
+			expect(caughtError.message).toContain(errorMatch);
+		} else {
+			expect(caughtError.message).toMatch(errorMatch);
+		}
+	}
+}
+
+/**
+ * Waits for a condition to be true
+ * @param condition - Function that returns true when condition is met
+ * @param timeout - Maximum time to wait in milliseconds (default: 1000)
+ * @param interval - Check interval in milliseconds (default: 50)
+ * @throws If timeout is reached before condition is met
+ */
+export async function waitForCondition(
+	condition: () => boolean | Promise<boolean>,
+	timeout = 1000,
+	interval = 50,
+): Promise<void> {
+	const startTime = Date.now();
+
+	while (Date.now() - startTime < timeout) {
+		const result = await condition();
+		if (result) {
+			return;
+		}
+		await delay(interval);
+	}
+
+	throw new Error(`Condition not met within ${timeout}ms`);
+}
+
+/**
+ * Delays execution for a specified amount of time
+ * @param ms - Milliseconds to delay
+ */
+export function delay(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Creates a spy function that records calls and arguments
+ * @returns Spy function with call tracking
+ */
+export function createSpy<TArgs extends unknown[], TReturn>(
+	implementation?: (...args: TArgs) => TReturn,
+): {
+	(...args: TArgs): TReturn;
+	calls: TArgs[];
+	callCount: number;
+	reset: () => void;
+} {
+	const calls: TArgs[] = [];
+
+	const spy = ((...args: TArgs) => {
+		calls.push(args);
+		if (implementation) {
+			return implementation(...args);
+		}
+		return undefined as TReturn;
+	}) as {
+		(...args: TArgs): TReturn;
+		calls: TArgs[];
+		callCount: number;
+		reset: () => void;
+	};
+
+	Object.defineProperty(spy, "calls", {
+		get: () => calls,
+	});
+
+	Object.defineProperty(spy, "callCount", {
+		get: () => calls.length,
+	});
+
+	spy.reset = () => {
+		calls.length = 0;
+	};
+
+	return spy;
+}
+
+/**
+ * Creates a mock function that returns predefined values
+ * @param returnValues - Array of values to return on consecutive calls
+ * @returns Mock function
+ */
+export function createMockFn<T>(...returnValues: T[]): () => T {
+	let callIndex = 0;
+
+	return () => {
+		if (callIndex >= returnValues.length) {
+			throw new Error("Mock function called more times than return values provided");
+		}
+		const value = returnValues[callIndex++];
+		if (value === undefined) {
+			throw new Error("Mock function returned undefined");
+		}
+		return value;
+	};
+}
+
+/**
+ * Creates a mock promise that can be resolved or rejected manually
+ * @returns Object with promise and resolve/reject functions
+ */
+export function createDeferredPromise<T>(): {
+	promise: Promise<T>;
+	resolve: (value: T) => void;
+	reject: (reason?: unknown) => void;
+} {
+	let resolveRef!: (value: T) => void;
+	let rejectRef!: (reason?: unknown) => void;
+
+	const promise = new Promise<T>((res, rej) => {
+		resolveRef = res;
+		rejectRef = rej;
+	});
+
+	return {
+		promise: promise,
+		resolve: resolveRef,
+		reject: rejectRef,
+	};
+}
+
+/**
+ * Captures console output during test execution
+ * @param fn - Function to execute while capturing output
+ * @returns Object with stdout and stderr arrays
+ */
+export async function captureConsole<T>(
+	fn: () => Promise<T> | T,
+): Promise<{ stdout: string[]; stderr: string[]; result: T }> {
+	const stdout: string[] = [];
+	const stderr: string[] = [];
+
+	const originalLog = console.log;
+	const originalError = console.error;
+	const originalWarn = console.warn;
+
+	console.log = (...args: unknown[]) => {
+		stdout.push(args.map(String).join(" "));
+	};
+
+	console.error = (...args: unknown[]) => {
+		stderr.push(args.map(String).join(" "));
+	};
+
+	console.warn = (...args: unknown[]) => {
+		stderr.push(args.map(String).join(" "));
+	};
+
+	try {
+		const result = await fn();
+		return { stdout, stderr, result };
+	} finally {
+		console.log = originalLog;
+		console.error = originalError;
+		console.warn = originalWarn;
+	}
+}
+
+/**
+ * Creates a unique temporary directory for tests in /tmp
+ * @param prefix - Optional prefix for the directory name (default: "omnidev-test-")
+ * @returns Path to the created temporary directory
+ */
+export function tmpdir(prefix = "omnidev-test-"): string {
+	return mkdtempSync(join(osTmpdir(), prefix));
+}
+
+export type TestDirOptions = {
+	chdir?: boolean;
+	createOmniDir?: boolean;
+};
+
+export type TestDirController = {
+	readonly path: string;
+	readonly originalCwd: string;
+	setPath: (path: string, options?: TestDirOptions) => void;
+	reset: (prefix?: string, options?: TestDirOptions & { cleanupPrevious?: boolean }) => string;
+};
+
+/**
+ * Sets up a temporary directory for each test and cleans it up automatically.
+ * Registers beforeEach/afterEach hooks on call.
+ */
+export function setupTestDir(
+	prefix = "omnidev-test-",
+	options: TestDirOptions = {},
+): TestDirController {
+	let currentDir = "";
+	let originalCwd = "";
+	let shouldChdir = options.chdir ?? false;
+	let shouldCreateOmniDir = options.createOmniDir ?? false;
+
+	const applyOptions = (dir: string, nextOptions?: TestDirOptions) => {
+		if (nextOptions) {
+			if (typeof nextOptions.chdir === "boolean") {
+				shouldChdir = nextOptions.chdir;
+			}
+			if (typeof nextOptions.createOmniDir === "boolean") {
+				shouldCreateOmniDir = nextOptions.createOmniDir;
+			}
+		}
+
+		if (shouldCreateOmniDir) {
+			mkdirSync(join(dir, ".omni"), { recursive: true });
+		}
+
+		if (shouldChdir) {
+			process.chdir(dir);
+		}
+	};
+
+	beforeEach(() => {
+		originalCwd = process.cwd();
+		currentDir = tmpdir(prefix);
+		applyOptions(currentDir);
+	});
+
+	afterEach(() => {
+		if (shouldChdir) {
+			process.chdir(originalCwd);
+		}
+		if (currentDir && existsSync(currentDir)) {
+			rmSync(currentDir, { recursive: true, force: true });
+		}
+	});
+
+	return {
+		get path() {
+			return currentDir;
+		},
+		get originalCwd() {
+			return originalCwd;
+		},
+		setPath(path: string, nextOptions?: TestDirOptions) {
+			currentDir = path;
+			applyOptions(currentDir, nextOptions);
+		},
+		reset(nextPrefix = prefix, nextOptions?: TestDirOptions & { cleanupPrevious?: boolean }) {
+			const cleanupPrevious = nextOptions?.cleanupPrevious ?? true;
+			if (cleanupPrevious && currentDir && existsSync(currentDir)) {
+				if (shouldChdir) {
+					process.chdir(originalCwd);
+				}
+				rmSync(currentDir, { recursive: true, force: true });
+			}
+			currentDir = tmpdir(nextPrefix);
+			applyOptions(currentDir, nextOptions);
+			return currentDir;
+		},
+	};
+}

package/src/test-utils/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Test utilities for OmniDev
+ *
+ * This module provides shared test utilities including:
+ * - Mock factories for creating test data
+ * - Helper functions for async testing
+ * - Spy and mock function utilities
+ */
+
+// Re-export all helper functions
+export {
+	captureConsole,
+	createDeferredPromise,
+	createMockFn,
+	createSpy,
+	delay,
+	expectToThrowAsync,
+	setupTestDir,
+	type TestDirController,
+	type TestDirOptions,
+	tmpdir,
+	waitForCondition,
+} from "./helpers";
+// Re-export all mock factories
+export {
+	createMockCapability,
+	createMockConfig,
+	createMockRule,
+	createMockSkill,
+	type MockCapability,
+	type MockConfig,
+	type MockRule,
+	type MockSkill,
+} from "./mocks";