@oh-my-pi/pi-coding-agent 2.3.1337 → 3.1.1337

package/src/discovery/github.ts

@@ -0,0 +1,120 @@
+/**
+ * GitHub Copilot Provider
+ *
+ * Loads configuration from GitHub Copilot's config directories.
+ * Priority: 30 (shared standard provider)
+ *
+ * Sources:
+ * - Project: .github/ (project-only, no user-level discovery)
+ *
+ * Capabilities:
+ * - context-files: copilot-instructions.md in .github/
+ * - instructions: *.instructions.md in .github/instructions/ with applyTo frontmatter
+ */
+
+import { basename, dirname, sep } from "node:path";
+import { type ContextFile, contextFileCapability } from "../capability/context-file";
+import { registerProvider } from "../capability/index";
+import { type Instruction, instructionCapability } from "../capability/instruction";
+import type { LoadContext, LoadResult, SourceMeta } from "../capability/types";
+import { calculateDepth, createSourceMeta, getProjectPath, loadFilesFromDir, parseFrontmatter } from "./helpers";
+
+const PROVIDER_ID = "github";
+const DISPLAY_NAME = "GitHub Copilot";
+const PRIORITY = 30;
+
+// =============================================================================
+// Context Files
+// =============================================================================
+
+function loadContextFiles(ctx: LoadContext): LoadResult<ContextFile> {
+	const items: ContextFile[] = [];
+	const warnings: string[] = [];
+
+	// Project-level: .github/copilot-instructions.md
+	const copilotInstructionsPath = getProjectPath(ctx, "github", "copilot-instructions.md");
+	if (copilotInstructionsPath && ctx.fs.isFile(copilotInstructionsPath)) {
+		const content = ctx.fs.readFile(copilotInstructionsPath);
+		if (content) {
+			const fileDir = dirname(copilotInstructionsPath);
+			const depth = calculateDepth(ctx.cwd, fileDir, sep);
+
+			items.push({
+				path: copilotInstructionsPath,
+				content,
+				level: "project",
+				depth,
+				_source: createSourceMeta(PROVIDER_ID, copilotInstructionsPath, "project"),
+			});
+		} else {
+			warnings.push(`Failed to read ${copilotInstructionsPath}`);
+		}
+	}
+
+	return { items, warnings };
+}
+
+// =============================================================================
+// Instructions
+// =============================================================================
+
+function loadInstructions(ctx: LoadContext): LoadResult<Instruction> {
+	const items: Instruction[] = [];
+	const warnings: string[] = [];
+
+	// Project-level: .github/instructions/*.instructions.md
+	const instructionsDir = getProjectPath(ctx, "github", "instructions");
+	if (instructionsDir && ctx.fs.isDir(instructionsDir)) {
+		const result = loadFilesFromDir<Instruction>(ctx, instructionsDir, PROVIDER_ID, "project", {
+			extensions: ["md"],
+			transform: transformInstruction,
+		});
+		items.push(...result.items);
+		if (result.warnings) warnings.push(...result.warnings);
+	}
+
+	return { items, warnings };
+}
+
+function transformInstruction(name: string, content: string, path: string, source: SourceMeta): Instruction | null {
+	// Only process .instructions.md files
+	if (!name.endsWith(".instructions.md")) {
+		return null;
+	}
+
+	const { frontmatter, body } = parseFrontmatter(content);
+
+	// Extract applyTo glob pattern from frontmatter
+	const applyTo = typeof frontmatter.applyTo === "string" ? frontmatter.applyTo : undefined;
+
+	// Derive name from filename (strip .instructions.md suffix)
+	const instructionName = basename(name, ".instructions.md");
+
+	return {
+		name: instructionName,
+		path,
+		content: body,
+		applyTo,
+		_source: source,
+	};
+}
+
+// =============================================================================
+// Provider Registration
+// =============================================================================
+
+registerProvider(contextFileCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Load copilot-instructions.md from .github/",
+	priority: PRIORITY,
+	load: loadContextFiles,
+});
+
+registerProvider(instructionCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Load *.instructions.md from .github/instructions/ with applyTo frontmatter",
+	priority: PRIORITY,
+	load: loadInstructions,
+});

package/src/discovery/helpers.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, test } from "vitest";
+import { parseFrontmatter } from "./helpers";
+
+describe("parseFrontmatter", () => {
+	test("parses simple key-value pairs", () => {
+		const content = `---
+name: test
+enabled: true
+---
+Body content`;
+
+		const result = parseFrontmatter(content);
+		expect(result.frontmatter).toEqual({ name: "test", enabled: true });
+		expect(result.body).toBe("Body content");
+	});
+
+	test("parses YAML list syntax", () => {
+		const content = `---
+tags:
+  - javascript
+  - typescript
+  - react
+---
+Body content`;
+
+		const result = parseFrontmatter(content);
+		expect(result.frontmatter).toEqual({
+			tags: ["javascript", "typescript", "react"],
+		});
+		expect(result.body).toBe("Body content");
+	});
+
+	test("parses multi-line string values", () => {
+		const content = `---
+description: |
+  This is a multi-line
+  description block
+  with several lines
+---
+Body content`;
+
+		const result = parseFrontmatter(content);
+		expect(result.frontmatter).toEqual({
+			description: "This is a multi-line\ndescription block\nwith several lines\n",
+		});
+		expect(result.body).toBe("Body content");
+	});
+
+	test("parses nested objects", () => {
+		const content = `---
+config:
+  server:
+    port: 3000
+    host: localhost
+  database:
+    name: mydb
+---
+Body content`;
+
+		const result = parseFrontmatter(content);
+		expect(result.frontmatter).toEqual({
+			config: {
+				server: { port: 3000, host: "localhost" },
+				database: { name: "mydb" },
+			},
+		});
+		expect(result.body).toBe("Body content");
+	});
+
+	test("parses mixed complex YAML", () => {
+		const content = `---
+name: complex-test
+version: 1.0.0
+tags:
+  - prod
+  - critical
+metadata:
+  author: tester
+  created: 2024-01-01
+description: |
+  Multi-line description
+  with formatting
+---
+Body content`;
+
+		const result = parseFrontmatter(content);
+		expect(result.frontmatter).toEqual({
+			name: "complex-test",
+			version: "1.0.0",
+			tags: ["prod", "critical"],
+			metadata: {
+				author: "tester",
+				created: "2024-01-01",
+			},
+			description: "Multi-line description\nwith formatting\n",
+		});
+		expect(result.body).toBe("Body content");
+	});
+
+	test("handles missing frontmatter", () => {
+		const content = "Just body content";
+		const result = parseFrontmatter(content);
+		expect(result.frontmatter).toEqual({});
+		expect(result.body).toBe("Just body content");
+	});
+
+	test("handles invalid YAML in frontmatter", () => {
+		const content = `---
+invalid: [unclosed array
+---
+Body content`;
+
+		const result = parseFrontmatter(content);
+		expect(result.frontmatter).toEqual({}); // Fallback to empty
+		expect(result.body).toBe("Body content");
+	});
+
+	test("handles empty frontmatter", () => {
+		const content = `---
+---
+Body content`;
+
+		const result = parseFrontmatter(content);
+		expect(result.frontmatter).toEqual({});
+		expect(result.body).toBe("Body content");
+	});
+});

package/src/discovery/helpers.ts

@@ -0,0 +1,249 @@
+/**
+ * Shared helpers for discovery providers.
+ */
+
+import { join, resolve } from "node:path";
+import { parse as parseYAML } from "yaml";
+import type { LoadContext, LoadResult, SourceMeta } from "../capability/types";
+
+/**
+ * Standard paths for each config source.
+ */
+export const SOURCE_PATHS = {
+	native: {
+		userBase: ".omp",
+		userAgent: ".omp/agent",
+		projectDir: ".omp",
+		aliases: [".pi"], // .pi is an alias for backwards compat
+	},
+	claude: {
+		userBase: ".claude",
+		userAgent: ".claude",
+		projectDir: ".claude",
+	},
+	codex: {
+		userBase: ".codex",
+		userAgent: ".codex",
+		projectDir: ".codex",
+	},
+	gemini: {
+		userBase: ".gemini",
+		userAgent: ".gemini",
+		projectDir: ".gemini",
+	},
+	cursor: {
+		userBase: ".cursor",
+		userAgent: ".cursor",
+		projectDir: ".cursor",
+	},
+	windsurf: {
+		userBase: ".codeium/windsurf",
+		userAgent: ".codeium/windsurf",
+		projectDir: ".windsurf",
+	},
+	cline: {
+		userBase: ".cline",
+		userAgent: ".cline",
+		projectDir: null, // Cline uses root-level .clinerules
+	},
+	github: {
+		userBase: null,
+		userAgent: null,
+		projectDir: ".github",
+	},
+	vscode: {
+		userBase: ".vscode",
+		userAgent: ".vscode",
+		projectDir: ".vscode",
+	},
+} as const;
+
+export type SourceId = keyof typeof SOURCE_PATHS;
+
+/**
+ * Get user-level path for a source.
+ */
+export function getUserPath(ctx: LoadContext, source: SourceId, subpath: string): string | null {
+	const paths = SOURCE_PATHS[source];
+	if (!paths.userAgent) return null;
+	return join(ctx.home, paths.userAgent, subpath);
+}
+
+/**
+ * Get project-level path for a source (walks up from cwd).
+ */
+export function getProjectPath(ctx: LoadContext, source: SourceId, subpath: string): string | null {
+	const paths = SOURCE_PATHS[source];
+	if (!paths.projectDir) return null;
+
+	const found = ctx.fs.walkUp(paths.projectDir, { dir: true });
+	if (!found) return null;
+
+	return join(found, subpath);
+}
+
+/**
+ * Create source metadata for an item.
+ */
+export function createSourceMeta(provider: string, path: string, level: "user" | "project"): SourceMeta {
+	return {
+		provider,
+		providerName: "", // Filled in by registry
+		path: resolve(path),
+		level,
+	};
+}
+
+/**
+ * Strip YAML frontmatter from content.
+ * Returns { frontmatter, body, raw }
+ */
+export function parseFrontmatter(content: string): {
+	frontmatter: Record<string, unknown>;
+	body: string;
+	raw: string;
+} {
+	const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+
+	if (!normalized.startsWith("---")) {
+		return { frontmatter: {}, body: normalized, raw: "" };
+	}
+
+	const endIndex = normalized.indexOf("\n---", 3);
+	if (endIndex === -1) {
+		return { frontmatter: {}, body: normalized, raw: "" };
+	}
+
+	const raw = normalized.slice(4, endIndex);
+	const body = normalized.slice(endIndex + 4).trim();
+
+	try {
+		const frontmatter = parseYAML(raw) as Record<string, unknown> | null;
+		return { frontmatter: frontmatter ?? {}, body, raw };
+	} catch {
+		// Fallback to empty frontmatter on parse error
+		return { frontmatter: {}, body, raw };
+	}
+}
+
+/**
+ * Expand environment variables in a string.
+ * Supports ${VAR} and ${VAR:-default} syntax.
+ */
+export function expandEnvVars(value: string, extraEnv?: Record<string, string>): string {
+	return value.replace(/\$\{([^}:]+)(?::-([^}]*))?\}/g, (_, varName: string, defaultValue?: string) => {
+		const envValue = extraEnv?.[varName] ?? process.env[varName];
+		if (envValue !== undefined) return envValue;
+		if (defaultValue !== undefined) return defaultValue;
+		return `\${${varName}}`;
+	});
+}
+
+/**
+ * Recursively expand environment variables in an object.
+ */
+export function expandEnvVarsDeep<T>(obj: T, extraEnv?: Record<string, string>): T {
+	if (typeof obj === "string") {
+		return expandEnvVars(obj, extraEnv) as T;
+	}
+	if (Array.isArray(obj)) {
+		return obj.map((item) => expandEnvVarsDeep(item, extraEnv)) as T;
+	}
+	if (obj !== null && typeof obj === "object") {
+		const result: Record<string, unknown> = {};
+		for (const [key, value] of Object.entries(obj)) {
+			result[key] = expandEnvVarsDeep(value, extraEnv);
+		}
+		return result as T;
+	}
+	return obj;
+}
+
+/**
+ * Load files from a directory matching a pattern.
+ */
+export function loadFilesFromDir<T>(
+	ctx: LoadContext,
+	dir: string,
+	provider: string,
+	level: "user" | "project",
+	options: {
+		/** File extensions to match (without dot) */
+		extensions?: string[];
+		/** Transform file to item (return null to skip) */
+		transform: (name: string, content: string, path: string, source: SourceMeta) => T | null;
+		/** Whether to recurse into subdirectories */
+		recursive?: boolean;
+	},
+): LoadResult<T> {
+	const items: T[] = [];
+	const warnings: string[] = [];
+
+	if (!ctx.fs.isDir(dir)) {
+		return { items, warnings };
+	}
+
+	const files = ctx.fs.readDir(dir);
+
+	for (const name of files) {
+		if (name.startsWith(".")) continue;
+
+		const path = join(dir, name);
+
+		if (options.recursive && ctx.fs.isDir(path)) {
+			const subResult = loadFilesFromDir(ctx, path, provider, level, options);
+			items.push(...subResult.items);
+			if (subResult.warnings) warnings.push(...subResult.warnings);
+			continue;
+		}
+
+		if (!ctx.fs.isFile(path)) continue;
+
+		// Check extension
+		if (options.extensions) {
+			const hasMatch = options.extensions.some((ext) => name.endsWith(`.${ext}`));
+			if (!hasMatch) continue;
+		}
+
+		const content = ctx.fs.readFile(path);
+		if (content === null) {
+			warnings.push(`Failed to read file: ${path}`);
+			continue;
+		}
+
+		const source = createSourceMeta(provider, path, level);
+
+		try {
+			const item = options.transform(name, content, path, source);
+			if (item !== null) {
+				items.push(item);
+			}
+		} catch (err) {
+			warnings.push(`Failed to parse ${path}: ${err}`);
+		}
+	}
+
+	return { items, warnings };
+}
+
+/**
+ * Parse JSON safely.
+ */
+export function parseJSON<T>(content: string): T | null {
+	try {
+		return JSON.parse(content) as T;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Calculate depth of target directory relative to current working directory.
+ * Depth is the number of directory levels from cwd to target.
+ * - Positive depth: target is above cwd (parent/ancestor)
+ * - Zero depth: target is cwd
+ * - This uses path splitting to count directory levels
+ */
+export function calculateDepth(cwd: string, targetDir: string, separator: string): number {
+	return cwd.split(separator).length - targetDir.split(separator).length;
+}

package/src/discovery/index.ts

@@ -0,0 +1,84 @@
+/**
+ * Discovery Module
+ *
+ * Auto-registers all providers by importing them.
+ * Import this module to ensure all providers are registered with the capability registry.
+ */
+
+// Import capability definitions (ensures capabilities are defined before providers register)
+import "../capability/context-file";
+import "../capability/extension";
+import "../capability/hook";
+import "../capability/instruction";
+import "../capability/mcp";
+import "../capability/prompt";
+import "../capability/rule";
+import "../capability/settings";
+import "../capability/skill";
+import "../capability/slash-command";
+import "../capability/system-prompt";
+import "../capability/tool";
+
+// Import providers (each registers itself on import)
+import "./builtin";
+import "./claude";
+import "./codex";
+import "./gemini";
+import "./cursor";
+import "./windsurf";
+import "./cline";
+import "./github";
+import "./vscode";
+import "./agents-md";
+import "./mcp-json";
+
+export type { ContextFile } from "../capability/context-file";
+export type { Extension, ExtensionManifest } from "../capability/extension";
+export type { Hook } from "../capability/hook";
+// Re-export the main API from capability registry
+export {
+	cacheStats,
+	// Provider management
+	disableProvider,
+	enableProvider,
+	getAllCapabilitiesInfo,
+	getAllProvidersInfo,
+	// Introspection
+	getCapability,
+	getCapabilityInfo,
+	getDisabledProviders,
+	getProviderInfo,
+	// Initialization
+	initializeWithSettings,
+	invalidate,
+	isProviderEnabled,
+	listCapabilities,
+	// Loading API
+	load,
+	loadSync,
+	// Cache management
+	reset,
+	setDisabledProviders,
+} from "../capability/index";
+export type { Instruction } from "../capability/instruction";
+// Re-export capability item types
+export type { MCPServer } from "../capability/mcp";
+export type { Prompt } from "../capability/prompt";
+export type { Rule, RuleFrontmatter } from "../capability/rule";
+export type { Settings } from "../capability/settings";
+export type { Skill, SkillFrontmatter } from "../capability/skill";
+export type { SlashCommand } from "../capability/slash-command";
+export type { SystemPrompt } from "../capability/system-prompt";
+export type { CustomTool } from "../capability/tool";
+// Re-export types
+export type {
+	Capability,
+	CapabilityInfo,
+	CapabilityResult,
+	LoadContext,
+	LoadOptions,
+	LoadResult,
+	Provider,
+	ProviderInfo,
+	SourceMeta,
+} from "../capability/types";

package/src/discovery/mcp-json.ts

@@ -0,0 +1,127 @@
+/**
+ * MCP JSON Provider
+ *
+ * Discovers standalone mcp.json / .mcp.json files in the project root.
+ * This is a fallback for projects that have a standalone mcp.json without any config directory.
+ *
+ * Priority: 5 (low, as this is a fallback after tool-specific providers)
+ */
+
+import { join } from "node:path";
+import { registerProvider } from "../capability/index";
+import { type MCPServer, mcpCapability } from "../capability/mcp";
+import type { LoadContext, LoadResult, SourceMeta } from "../capability/types";
+import { createSourceMeta, expandEnvVarsDeep, parseJSON } from "./helpers";
+
+const PROVIDER_ID = "mcp-json";
+const DISPLAY_NAME = "MCP Config";
+
+/**
+ * Raw MCP JSON format (matches Claude Desktop's format).
+ */
+interface MCPConfigFile {
+	mcpServers?: Record<
+		string,
+		{
+			command?: string;
+			args?: string[];
+			env?: Record<string, string>;
+			url?: string;
+			headers?: Record<string, string>;
+			type?: "stdio" | "sse" | "http";
+		}
+	>;
+}
+
+/**
+ * Transform raw MCP config to canonical MCPServer format.
+ */
+function transformMCPConfig(config: MCPConfigFile, source: SourceMeta): MCPServer[] {
+	const servers: MCPServer[] = [];
+
+	if (config.mcpServers) {
+		for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
+			const server: MCPServer = {
+				name,
+				command: serverConfig.command,
+				args: serverConfig.args,
+				env: serverConfig.env,
+				url: serverConfig.url,
+				headers: serverConfig.headers,
+				transport: serverConfig.type,
+				_source: source,
+			};
+
+			// Expand environment variables
+			if (server.command) server.command = expandEnvVarsDeep(server.command);
+			if (server.args) server.args = expandEnvVarsDeep(server.args);
+			if (server.env) server.env = expandEnvVarsDeep(server.env);
+			if (server.url) server.url = expandEnvVarsDeep(server.url);
+			if (server.headers) server.headers = expandEnvVarsDeep(server.headers);
+
+			servers.push(server);
+		}
+	}
+
+	return servers;
+}
+
+/**
+ * Load MCP servers from a JSON file.
+ */
+function loadMCPJsonFile(ctx: LoadContext, path: string, level: "user" | "project"): LoadResult<MCPServer> {
+	const warnings: string[] = [];
+	const items: MCPServer[] = [];
+
+	if (!ctx.fs.isFile(path)) {
+		return { items, warnings };
+	}
+
+	const content = ctx.fs.readFile(path);
+	if (content === null) {
+		warnings.push(`Failed to read ${path}`);
+		return { items, warnings };
+	}
+
+	const config = parseJSON<MCPConfigFile>(content);
+	if (!config) {
+		warnings.push(`Failed to parse JSON in ${path}`);
+		return { items, warnings };
+	}
+
+	const source = createSourceMeta(PROVIDER_ID, path, level);
+	const servers = transformMCPConfig(config, source);
+	items.push(...servers);
+
+	return { items, warnings };
+}
+
+/**
+ * MCP JSON Provider loader.
+ */
+function load(ctx: LoadContext): LoadResult<MCPServer> {
+	const allItems: MCPServer[] = [];
+	const allWarnings: string[] = [];
+
+	// Check for mcp.json or .mcp.json in project root (cwd)
+	for (const filename of ["mcp.json", ".mcp.json"]) {
+		const path = join(ctx.cwd, filename);
+		const result = loadMCPJsonFile(ctx, path, "project");
+		allItems.push(...result.items);
+		if (result.warnings) allWarnings.push(...result.warnings);
+	}
+
+	return {
+		items: allItems,
+		warnings: allWarnings.length > 0 ? allWarnings : undefined,
+	};
+}
+
+// Register provider
+registerProvider(mcpCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Load MCP servers from standalone mcp.json or .mcp.json in project root",
+	priority: 5,
+	load,
+});