@f5xc-salesdemos/xcsh 2.2.0 → 14.0.2

package/src/discovery/index.ts

@@ -0,0 +1,79 @@
+/**
+ * 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/extension-module";
+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/ssh";
+import "../capability/system-prompt";
+import "../capability/tool";
+// Import providers (each registers itself on import)
+import "./agents-md";
+import "./builtin";
+import "./claude";
+import "./claude-plugins";
+import "./cline";
+import "./agents";
+import "./codex";
+import "./cursor";
+import "./gemini";
+import "./opencode";
+import "./github";
+import "./mcp-json";
+import "./ssh";
+import "./vscode";
+import "./windsurf";
+
+// 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
+	loadCapability,
+	// Cache management
+	reset,
+	setDisabledProviders,
+} from "../capability";
+export type { ContextFile } from "../capability/context-file";
+export type { Extension, ExtensionManifest } from "../capability/extension";
+export type { ExtensionModule } from "../capability/extension-module";
+export type { Hook } from "../capability/hook";
+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 { SSHHost } from "../capability/ssh";
+export type { SystemPrompt } from "../capability/system-prompt";
+export type { CustomTool } from "../capability/tool";
+// Re-export types
+export type * from "../capability/types";

package/src/discovery/mcp-json.ts

@@ -0,0 +1,171 @@
+/**
+ * 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 * as path from "node:path";
+import { logger, tryParseJson } from "@f5xc-salesdemos/pi-utils";
+import { registerProvider } from "../capability";
+import { readFile } from "../capability/fs";
+import { type MCPServer, mcpCapability } from "../capability/mcp";
+import type { LoadContext, LoadResult, SourceMeta } from "../capability/types";
+import { createSourceMeta, expandEnvVarsDeep } 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,
+		{
+			enabled?: boolean;
+			timeout?: number;
+			command?: string;
+			args?: string[];
+			env?: Record<string, string>;
+			cwd?: string;
+			url?: string;
+			headers?: Record<string, string>;
+			auth?: {
+				type: "oauth" | "apikey";
+				credentialId?: string;
+				tokenUrl?: string;
+				clientId?: string;
+				clientSecret?: string;
+			};
+			type?: "stdio" | "sse" | "http";
+			oauth?: {
+				clientId?: string;
+				clientSecret?: string;
+				redirectUri?: string;
+				callbackPort?: number;
+				callbackPath?: string;
+			};
+		}
+	>;
+}
+
+/**
+ * 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)) {
+			// Runtime type validation for user-controlled JSON values
+			let enabled: boolean | undefined;
+			if (serverConfig.enabled !== undefined) {
+				if (typeof serverConfig.enabled === "boolean") {
+					enabled = serverConfig.enabled;
+				} else {
+					logger.warn("MCP server has invalid 'enabled' value, ignoring", { name, value: serverConfig.enabled });
+				}
+			}
+
+			let timeout: number | undefined;
+			if (serverConfig.timeout !== undefined) {
+				if (
+					typeof serverConfig.timeout === "number" &&
+					Number.isFinite(serverConfig.timeout) &&
+					serverConfig.timeout > 0
+				) {
+					timeout = serverConfig.timeout;
+				} else {
+					logger.warn("MCP server has invalid 'timeout' value, ignoring", { name, value: serverConfig.timeout });
+				}
+			}
+
+			const server: MCPServer = {
+				name,
+				enabled,
+				timeout,
+				command: serverConfig.command,
+				args: serverConfig.args,
+				env: serverConfig.env,
+				cwd: serverConfig.cwd,
+				url: serverConfig.url,
+				headers: serverConfig.headers,
+				auth: serverConfig.auth,
+				oauth: serverConfig.oauth,
+				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.cwd) server.cwd = expandEnvVarsDeep(server.cwd);
+			if (server.url) server.url = expandEnvVarsDeep(server.url);
+			if (server.headers) server.headers = expandEnvVarsDeep(server.headers);
+			if (server.auth) server.auth = expandEnvVarsDeep(server.auth);
+			if (server.oauth) server.oauth = expandEnvVarsDeep(server.oauth);
+			servers.push(server);
+		}
+	}
+
+	return servers;
+}
+
+/**
+ * Load MCP servers from a JSON file.
+ */
+async function loadMCPJsonFile(
+	_ctx: LoadContext,
+	path: string,
+	level: "user" | "project",
+): Promise<LoadResult<MCPServer>> {
+	const warnings: string[] = [];
+	const items: MCPServer[] = [];
+
+	const content = await readFile(path);
+	if (content === null) {
+		return { items, warnings };
+	}
+
+	const config = tryParseJson<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.
+ */
+async function load(ctx: LoadContext): Promise<LoadResult<MCPServer>> {
+	const filenames = ["mcp.json", ".mcp.json"];
+	const results = await Promise.all(
+		filenames.map(filename => loadMCPJsonFile(ctx, path.join(ctx.cwd, filename), "project")),
+	);
+
+	const allItems = results.flatMap(r => r.items);
+	const allWarnings = results.flatMap(r => r.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,
+});

package/src/discovery/opencode.ts

@@ -0,0 +1,393 @@
+/**
+ * OpenCode Discovery Provider
+ *
+ * Loads configuration from OpenCode's config directories:
+ * - User: ~/.config/opencode/
+ * - Project: .opencode/ (cwd) and opencode.json (project root)
+ *
+ * Capabilities:
+ * - context-files: AGENTS.md (user-level only at ~/.config/opencode/AGENTS.md)
+ * - mcps: From opencode.json "mcp" key
+ * - settings: From opencode.json
+ * - skills: From skills/ subdirectories
+ * - slash-commands: From commands/ subdirectories
+ * - extension-modules: From plugins/ subdirectories
+ *
+ * Priority: 55 (tool-specific provider)
+ */
+import * as path from "node:path";
+import { logger, parseFrontmatter, tryParseJson } from "@f5xc-salesdemos/pi-utils";
+import { registerProvider } from "../capability";
+import { type ContextFile, contextFileCapability } from "../capability/context-file";
+import { type ExtensionModule, extensionModuleCapability } from "../capability/extension-module";
+import { readFile } from "../capability/fs";
+import { type MCPServer, mcpCapability } from "../capability/mcp";
+import { type Settings, settingsCapability } from "../capability/settings";
+import { type Skill, skillCapability } from "../capability/skill";
+import { type SlashCommand, slashCommandCapability } from "../capability/slash-command";
+import type { LoadContext, LoadResult, SourceMeta } from "../capability/types";
+
+import {
+	createSourceMeta,
+	discoverExtensionModulePaths,
+	expandEnvVarsDeep,
+	getExtensionNameFromPath,
+	getProjectPath,
+	getUserPath,
+	loadFilesFromDir,
+	scanSkillsFromDir,
+} from "./helpers";
+
+const PROVIDER_ID = "opencode";
+const DISPLAY_NAME = "OpenCode";
+const PRIORITY = 55;
+
+// =============================================================================
+// JSON Config Loading
+// =============================================================================
+
+async function loadJsonConfig(configPath: string): Promise<Record<string, unknown> | null> {
+	const content = await readFile(configPath);
+	if (!content) return null;
+
+	const parsed = tryParseJson<Record<string, unknown>>(content);
+	if (!parsed) {
+		logger.warn("Failed to parse OpenCode JSON config", { path: configPath });
+		return null;
+	}
+	return parsed;
+}
+
+// =============================================================================
+// Context Files (AGENTS.md)
+// =============================================================================
+
+async function loadContextFiles(ctx: LoadContext): Promise<LoadResult<ContextFile>> {
+	const items: ContextFile[] = [];
+	const warnings: string[] = [];
+
+	// User-level only: ~/.config/opencode/AGENTS.md
+	const userAgentsMd = getUserPath(ctx, "opencode", "AGENTS.md");
+	if (userAgentsMd) {
+		const content = await readFile(userAgentsMd);
+		if (content) {
+			items.push({
+				path: userAgentsMd,
+				content,
+				level: "user",
+				_source: createSourceMeta(PROVIDER_ID, userAgentsMd, "user"),
+			});
+		}
+	}
+
+	return { items, warnings };
+}
+
+// =============================================================================
+// MCP Servers (opencode.json → mcp)
+// =============================================================================
+
+/** OpenCode MCP server config (from opencode.json "mcp" key) */
+interface OpenCodeMCPConfig {
+	type?: "local" | "remote";
+	command?: string;
+	args?: string[];
+	env?: Record<string, string>;
+	url?: string;
+	headers?: Record<string, string>;
+	enabled?: boolean;
+	timeout?: number;
+}
+
+async function loadMCPServers(ctx: LoadContext): Promise<LoadResult<MCPServer>> {
+	const items: MCPServer[] = [];
+	const warnings: string[] = [];
+
+	// User-level: ~/.config/opencode/opencode.json
+	const userConfigPath = getUserPath(ctx, "opencode", "opencode.json");
+	if (userConfigPath) {
+		const config = await loadJsonConfig(userConfigPath);
+		if (config) {
+			const result = extractMCPServers(config, userConfigPath, "user");
+			items.push(...result.items);
+			if (result.warnings) warnings.push(...result.warnings);
+		}
+	}
+
+	// Project-level: opencode.json in project root
+	const projectConfigPath = path.join(ctx.cwd, "opencode.json");
+	const projectConfig = await loadJsonConfig(projectConfigPath);
+	if (projectConfig) {
+		const result = extractMCPServers(projectConfig, projectConfigPath, "project");
+		items.push(...result.items);
+		if (result.warnings) warnings.push(...result.warnings);
+	}
+
+	return { items, warnings };
+}
+
+function extractMCPServers(
+	config: Record<string, unknown>,
+	configPath: string,
+	level: "user" | "project",
+): LoadResult<MCPServer> {
+	const items: MCPServer[] = [];
+	const warnings: string[] = [];
+
+	if (!config.mcp || typeof config.mcp !== "object") {
+		return { items, warnings };
+	}
+
+	const servers = expandEnvVarsDeep(config.mcp as Record<string, unknown>);
+
+	for (const [name, raw] of Object.entries(servers)) {
+		if (!raw || typeof raw !== "object") {
+			warnings.push(`Invalid MCP config for "${name}" in ${configPath}`);
+			continue;
+		}
+
+		const serverConfig = raw as OpenCodeMCPConfig;
+
+		// Determine transport from OpenCode's "type" field
+		let transport: "stdio" | "sse" | "http" | undefined;
+		if (serverConfig.type === "local") {
+			transport = "stdio";
+		} else if (serverConfig.type === "remote") {
+			transport = "http";
+		} else if (serverConfig.url) {
+			transport = "http";
+		} else if (serverConfig.command) {
+			transport = "stdio";
+		}
+
+		items.push({
+			name,
+			command: serverConfig.command,
+			args: Array.isArray(serverConfig.args) ? (serverConfig.args as string[]) : undefined,
+			env: serverConfig.env && typeof serverConfig.env === "object" ? serverConfig.env : undefined,
+			url: typeof serverConfig.url === "string" ? serverConfig.url : undefined,
+			headers: serverConfig.headers && typeof serverConfig.headers === "object" ? serverConfig.headers : undefined,
+			enabled: serverConfig.enabled,
+			timeout: typeof serverConfig.timeout === "number" ? serverConfig.timeout : undefined,
+			transport,
+			_source: createSourceMeta(PROVIDER_ID, configPath, level),
+		});
+	}
+
+	return { items, warnings };
+}
+
+// =============================================================================
+// Skills (skills/)
+// =============================================================================
+
+async function loadSkills(ctx: LoadContext): Promise<LoadResult<Skill>> {
+	const userSkillsDir = getUserPath(ctx, "opencode", "skills");
+	const projectSkillsDir = getProjectPath(ctx, "opencode", "skills");
+
+	const promises: Promise<LoadResult<Skill>>[] = [];
+
+	if (userSkillsDir) {
+		promises.push(
+			scanSkillsFromDir(ctx, {
+				dir: userSkillsDir,
+				providerId: PROVIDER_ID,
+				level: "user",
+			}),
+		);
+	}
+
+	if (projectSkillsDir) {
+		promises.push(
+			scanSkillsFromDir(ctx, {
+				dir: projectSkillsDir,
+				providerId: PROVIDER_ID,
+				level: "project",
+			}),
+		);
+	}
+
+	const results = await Promise.all(promises);
+	const items = results.flatMap(r => r.items);
+	const warnings = results.flatMap(r => r.warnings || []);
+
+	return { items, warnings };
+}
+
+// =============================================================================
+// Extension Modules (plugins/)
+// =============================================================================
+
+async function loadExtensionModules(ctx: LoadContext): Promise<LoadResult<ExtensionModule>> {
+	const userPluginsDir = getUserPath(ctx, "opencode", "plugins");
+	const projectPluginsDir = getProjectPath(ctx, "opencode", "plugins");
+
+	const [userPaths, projectPaths] = await Promise.all([
+		userPluginsDir ? discoverExtensionModulePaths(ctx, userPluginsDir) : Promise.resolve([]),
+		projectPluginsDir ? discoverExtensionModulePaths(ctx, projectPluginsDir) : Promise.resolve([]),
+	]);
+
+	const items: ExtensionModule[] = [
+		...userPaths.map(extPath => ({
+			name: getExtensionNameFromPath(extPath),
+			path: extPath,
+			level: "user" as const,
+			_source: createSourceMeta(PROVIDER_ID, extPath, "user"),
+		})),
+		...projectPaths.map(extPath => ({
+			name: getExtensionNameFromPath(extPath),
+			path: extPath,
+			level: "project" as const,
+			_source: createSourceMeta(PROVIDER_ID, extPath, "project"),
+		})),
+	];
+
+	return { items, warnings: [] };
+}
+
+// =============================================================================
+// Slash Commands (commands/)
+// =============================================================================
+
+async function loadSlashCommands(ctx: LoadContext): Promise<LoadResult<SlashCommand>> {
+	const userCommandsDir = getUserPath(ctx, "opencode", "commands");
+	const projectCommandsDir = getProjectPath(ctx, "opencode", "commands");
+
+	const transformCommand =
+		(level: "user" | "project") => (name: string, content: string, filePath: string, source: SourceMeta) => {
+			const { frontmatter, body } = parseFrontmatter(content, { source: filePath });
+			const commandName = frontmatter.name || name.replace(/\.md$/, "");
+			return {
+				name: String(commandName),
+				path: filePath,
+				content: body,
+				level,
+				_source: source,
+			};
+		};
+
+	const promises: Promise<LoadResult<SlashCommand>>[] = [];
+
+	if (userCommandsDir) {
+		promises.push(
+			loadFilesFromDir(ctx, userCommandsDir, PROVIDER_ID, "user", {
+				extensions: ["md"],
+				transform: transformCommand("user"),
+			}),
+		);
+	}
+
+	if (projectCommandsDir) {
+		promises.push(
+			loadFilesFromDir(ctx, projectCommandsDir, PROVIDER_ID, "project", {
+				extensions: ["md"],
+				transform: transformCommand("project"),
+			}),
+		);
+	}
+
+	const results = await Promise.all(promises);
+	const items = results.flatMap(r => r.items);
+	const warnings = results.flatMap(r => r.warnings || []);
+
+	return { items, warnings };
+}
+
+// =============================================================================
+// Settings (opencode.json)
+// =============================================================================
+
+async function loadSettings(ctx: LoadContext): Promise<LoadResult<Settings>> {
+	const items: Settings[] = [];
+	const warnings: string[] = [];
+
+	// User-level: ~/.config/opencode/opencode.json
+	const userConfigPath = getUserPath(ctx, "opencode", "opencode.json");
+	if (userConfigPath) {
+		const content = await readFile(userConfigPath);
+		if (content) {
+			const parsed = tryParseJson<Record<string, unknown>>(content);
+			if (parsed) {
+				items.push({
+					path: userConfigPath,
+					data: parsed,
+					level: "user",
+					_source: createSourceMeta(PROVIDER_ID, userConfigPath, "user"),
+				});
+			} else {
+				warnings.push(`Invalid JSON in ${userConfigPath}`);
+			}
+		}
+	}
+
+	// Project-level: opencode.json in project root
+	const projectConfigPath = path.join(ctx.cwd, "opencode.json");
+	const content = await readFile(projectConfigPath);
+	if (content) {
+		const parsed = tryParseJson<Record<string, unknown>>(content);
+		if (parsed) {
+			items.push({
+				path: projectConfigPath,
+				data: parsed,
+				level: "project",
+				_source: createSourceMeta(PROVIDER_ID, projectConfigPath, "project"),
+			});
+		} else {
+			warnings.push(`Invalid JSON in ${projectConfigPath}`);
+		}
+	}
+
+	return { items, warnings };
+}
+
+// =============================================================================
+// Provider Registration
+// =============================================================================
+
+registerProvider(contextFileCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Load AGENTS.md from ~/.config/opencode/",
+	priority: PRIORITY,
+	load: loadContextFiles,
+});
+
+registerProvider(mcpCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Load MCP servers from opencode.json mcp key",
+	priority: PRIORITY,
+	load: loadMCPServers,
+});
+
+registerProvider(skillCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Load skills from ~/.config/opencode/skills/ and .opencode/skills/",
+	priority: PRIORITY,
+	load: loadSkills,
+});
+
+registerProvider(extensionModuleCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Load extension modules from ~/.config/opencode/plugins/ and .opencode/plugins/",
+	priority: PRIORITY,
+	load: loadExtensionModules,
+});
+
+registerProvider(slashCommandCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Load slash commands from ~/.config/opencode/commands/ and .opencode/commands/",
+	priority: PRIORITY,
+	load: loadSlashCommands,
+});
+
+registerProvider(settingsCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Load settings from opencode.json",
+	priority: PRIORITY,
+	load: loadSettings,
+});

package/src/discovery/plugin-dir-roots.ts

@@ -0,0 +1,28 @@
+import * as path from "node:path";
+
+/** Synthetic plugin root for a --plugin-dir path. Shape-compatible with ClaudePluginRoot. */
+export interface PluginDirRoot {
+	id: string;
+	marketplace: string;
+	plugin: string;
+	version: string;
+	path: string;
+	scope: "user" | "project";
+}
+
+/**
+ * Build a synthetic plugin root from a --plugin-dir resolved path.
+ * @param resolvedPath Absolute path to the plugin directory
+ * @param manifestName Plugin name from manifest; falls back to directory basename
+ */
+export function buildPluginDirRoot(resolvedPath: string, manifestName?: string): PluginDirRoot {
+	const pluginName = manifestName || path.basename(resolvedPath);
+	return {
+		id: `${pluginName}@__local__`,
+		marketplace: "__local__",
+		plugin: pluginName,
+		version: "local",
+		path: resolvedPath,
+		scope: "user",
+	};
+}