@oh-my-pi/pi-coding-agent 13.16.5 → 13.17.0

package/src/discovery/claude-plugins.ts

@@ -5,13 +5,24 @@
  * Priority: 70 (below claude.ts at 80, so user overrides in .claude/ take precedence)
  */
 import * as path from "node:path";
+import { logger } from "@oh-my-pi/pi-utils";
 import { registerProvider } from "../capability";
+import { readFile } from "../capability/fs";
 import { type Hook, hookCapability } from "../capability/hook";
+import { type MCPServer, mcpCapability } from "../capability/mcp";
 import { type Skill, skillCapability } from "../capability/skill";
 import { type SlashCommand, slashCommandCapability } from "../capability/slash-command";
 import { type CustomTool, toolCapability } from "../capability/tool";
 import type { LoadContext, LoadResult } from "../capability/types";
-import { type ClaudePluginRoot, listClaudePluginRoots, loadFilesFromDir, scanSkillsFromDir } from "./helpers";
+import {
+	type ClaudePluginRoot,
+	createSourceMeta,
+	listClaudePluginRoots,
+	loadFilesFromDir,
+	scanSkillsFromDir,
+} from "./helpers";
+
+import { substitutePluginRoot } from "./substitute-plugin-root";
 
 const PROVIDER_ID = "claude-plugins";
 const DISPLAY_NAME = "Claude Code Marketplace";
@@ -31,16 +42,20 @@ async function loadSkills(ctx: LoadContext): Promise<LoadResult<Skill>> {
 	const results = await Promise.all(
 		roots.map(async root => {
 			const skillsDir = path.join(root.path, "skills");
-			return scanSkillsFromDir(ctx, {
+			const result = await scanSkillsFromDir(ctx, {
 				dir: skillsDir,
 				providerId: PROVIDER_ID,
 				level: root.scope,
 			});
+			return { root, result };
 		}),
 	);
 
-	for (const result of results) {
-		items.push(...result.items);
+	for (const { root, result } of results) {
+		for (const skill of result.items) {
+			if (root.plugin) skill.name = `${root.plugin}:${skill.name}`;
+			items.push(skill);
+		}
 		if (result.warnings) warnings.push(...result.warnings);
 	}
 
@@ -66,7 +81,7 @@ async function loadSlashCommands(ctx: LoadContext): Promise<LoadResult<SlashComm
 				transform: (name, content, filePath, source) => {
 					const cmdName = name.replace(/\.md$/, "");
 					return {
-						name: cmdName,
+						name: root.plugin ? `${root.plugin}:${cmdName}` : cmdName,
 						path: filePath,
 						content,
 						level: root.scope,
@@ -169,6 +184,73 @@ async function loadTools(ctx: LoadContext): Promise<LoadResult<CustomTool>> {
 	return { items, warnings };
 }
 
+// =============================================================================
+// MCP Servers
+// =============================================================================
+
+async function loadMCPServers(ctx: LoadContext): Promise<LoadResult<MCPServer>> {
+	const items: MCPServer[] = [];
+	const warnings: string[] = [];
+
+	const { roots, warnings: rootWarnings } = await listClaudePluginRoots(ctx.home);
+	warnings.push(...rootWarnings);
+
+	for (const root of roots) {
+		const mcpPath = path.join(root.path, ".mcp.json");
+		const raw = await readFile(mcpPath);
+		if (raw === null) continue; // file absent — skip silently
+
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(raw);
+		} catch {
+			warnings.push(`[claude-plugins] Invalid JSON in ${mcpPath}`);
+			logger.warn(`[claude-plugins] Invalid JSON in ${mcpPath}`);
+			continue;
+		}
+
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+		const config = parsed as { mcpServers?: Record<string, unknown> };
+		if (!config.mcpServers || typeof config.mcpServers !== "object") continue;
+
+		for (const [serverName, serverCfg] of Object.entries(config.mcpServers)) {
+			if (!serverCfg || typeof serverCfg !== "object" || Array.isArray(serverCfg)) continue;
+			const raw = serverCfg as {
+				enabled?: boolean;
+				timeout?: number;
+				command?: string;
+				args?: string[];
+				env?: Record<string, string>;
+				cwd?: string;
+				url?: string;
+				headers?: Record<string, string>;
+				auth?: MCPServer["auth"];
+				oauth?: MCPServer["oauth"];
+				type?: string;
+			};
+			const namespacedName = root.plugin ? `${root.plugin}:${serverName}` : serverName;
+			const server: MCPServer = {
+				name: namespacedName,
+				...(raw.enabled !== undefined && { enabled: raw.enabled }),
+				...(raw.timeout !== undefined && { timeout: raw.timeout }),
+				...(raw.command !== undefined && { command: substitutePluginRoot(raw.command, root.path) }),
+				...(raw.args !== undefined && { args: substitutePluginRoot(raw.args, root.path) }),
+				...(raw.env !== undefined && { env: substitutePluginRoot(raw.env, root.path) }),
+				...(raw.cwd !== undefined && { cwd: substitutePluginRoot(raw.cwd, root.path) }),
+				...(raw.url !== undefined && { url: raw.url }),
+				...(raw.headers !== undefined && { headers: raw.headers }),
+				...(raw.auth !== undefined && { auth: raw.auth }),
+				...(raw.oauth !== undefined && { oauth: raw.oauth }),
+				...(raw.type !== undefined && { transport: raw.type as MCPServer["transport"] }),
+				_source: createSourceMeta(PROVIDER_ID, mcpPath, root.scope),
+			};
+			items.push(server);
+		}
+	}
+
+	return { items, warnings };
+}
+
 // =============================================================================
 // Provider Registration
 // =============================================================================
@@ -204,3 +286,11 @@ registerProvider<CustomTool>(toolCapability.id, {
 	priority: PRIORITY,
 	load: loadTools,
 });
+
+registerProvider<MCPServer>(mcpCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Load MCP servers from marketplace plugin .mcp.json files",
+	priority: PRIORITY,
+	load: loadMCPServers,
+});

package/src/discovery/helpers.ts

@@ -9,6 +9,7 @@ import type { Skill, SkillFrontmatter } from "../capability/skill";
 import type { LoadContext, LoadResult, SourceMeta } from "../capability/types";
 import { parseThinkingLevel } from "../thinking";
 import { parseFrontmatter } from "../utils/frontmatter";
+import { buildPluginDirRoot } from "./plugin-dir-roots";
 
 /**
  * Standard paths for each config source.
@@ -593,6 +594,7 @@ export interface ClaudePluginEntry {
 	installedAt: string;
 	lastUpdated: string;
 	gitCommitSha?: string;
+	enabled?: boolean;
 }
 
 /**
@@ -652,56 +654,106 @@ export async function listClaudePluginRoots(home: string): Promise<{ roots: Clau
 	const roots: ClaudePluginRoot[] = [];
 	const warnings: string[] = [];
 
+	// ── Claude Code registry ──────────────────────────────────────────────────
 	const registryPath = path.join(home, ".claude", "plugins", "installed_plugins.json");
 	const content = await readFile(registryPath);
 
-	if (!content) {
-		// No registry file - not an error, just no plugins
-		const result = { roots, warnings };
-		pluginRootsCache.set(home, result);
-		return result;
-	}
-
-	const registry = parseClaudePluginsRegistry(content);
-	if (!registry) {
-		warnings.push(`Failed to parse Claude Code plugin registry: ${registryPath}`);
-		const result = { roots, warnings };
-		pluginRootsCache.set(home, result);
-		return result;
-	}
-
-	for (const [pluginId, entries] of Object.entries(registry.plugins)) {
-		if (!Array.isArray(entries) || entries.length === 0) continue;
-
-		// Parse plugin ID format: "plugin-name@marketplace"
-		const atIndex = pluginId.lastIndexOf("@");
-		if (atIndex === -1) {
-			warnings.push(`Invalid plugin ID format (missing @marketplace): ${pluginId}`);
-			continue;
+	if (content) {
+		const registry = parseClaudePluginsRegistry(content);
+		if (!registry) {
+			warnings.push(`Failed to parse Claude Code plugin registry: ${registryPath}`);
+		} else {
+			for (const [pluginId, entries] of Object.entries(registry.plugins)) {
+				if (!Array.isArray(entries) || entries.length === 0) continue;
+
+				// Parse plugin ID format: "plugin-name@marketplace"
+				const atIndex = pluginId.lastIndexOf("@");
+				if (atIndex === -1) {
+					warnings.push(`Invalid plugin ID format (missing @marketplace): ${pluginId}`);
+					continue;
+				}
+
+				const pluginName = pluginId.slice(0, atIndex);
+				const marketplace = pluginId.slice(atIndex + 1);
+
+				// Process all valid entries, not just the first one.
+				// This handles plugins with multiple installs (different scopes/versions).
+				for (const entry of entries) {
+					if (!entry.installPath || typeof entry.installPath !== "string") {
+						warnings.push(`Plugin ${pluginId} entry has no installPath`);
+						continue;
+					}
+					if (entry.enabled === false) continue;
+
+					roots.push({
+						id: pluginId,
+						marketplace,
+						plugin: pluginName,
+						version: entry.version || "unknown",
+						path: entry.installPath,
+						scope: entry.scope || "user",
+					});
+				}
+			}
 		}
+	}
 
-		const pluginName = pluginId.slice(0, atIndex);
-		const marketplace = pluginId.slice(atIndex + 1);
-
-		// Process all valid entries, not just the first one.
-		// This handles plugins with multiple installs (different scopes/versions).
-		for (const entry of entries) {
-			if (!entry.installPath || typeof entry.installPath !== "string") {
-				warnings.push(`Plugin ${pluginId} entry has no installPath`);
-				continue;
+	// ── OMP installed plugins registry ───────────────────────────────────────
+	// OMP registry is authoritative: its entries replace Claude's entries for the same plugin ID.
+	// Path derived from `home` (not os.homedir()) so test isolation works when home is overridden.
+	const ompRegistryPath = path.join(home, getConfigDirName(), "plugins", "installed_plugins.json");
+	const ompContent = await readFile(ompRegistryPath);
+	if (ompContent) {
+		const ompRegistry = parseClaudePluginsRegistry(ompContent);
+		if (ompRegistry) {
+			for (const [pluginId, entries] of Object.entries(ompRegistry.plugins)) {
+				if (!Array.isArray(entries) || entries.length === 0) continue;
+
+				const atIndex = pluginId.lastIndexOf("@");
+				if (atIndex === -1) {
+					warnings.push(`Invalid plugin ID format (missing @marketplace): ${pluginId}`);
+					continue;
+				}
+				const pluginName = pluginId.slice(0, atIndex);
+				const marketplace = pluginId.slice(atIndex + 1);
+
+				// OMP is authoritative: drop all Claude-sourced entries for this plugin ID
+				const filtered = roots.filter(r => r.id !== pluginId);
+				roots.length = 0;
+				roots.push(...filtered);
+
+				for (const entry of entries) {
+					if (!entry.installPath || typeof entry.installPath !== "string") {
+						warnings.push(`Plugin ${pluginId} entry has no installPath`);
+						continue;
+					}
+					if (entry.enabled === false) continue;
+					// Deduplicate by installPath within same ID
+					if (roots.some(r => r.id === pluginId && r.path === entry.installPath)) continue;
+
+					roots.push({
+						id: pluginId,
+						marketplace,
+						plugin: pluginName,
+						version: entry.version || "unknown",
+						path: entry.installPath,
+						scope: entry.scope || "user",
+					});
+				}
 			}
-
-			roots.push({
-				id: pluginId,
-				marketplace,
-				plugin: pluginName,
-				version: entry.version || "unknown",
-				path: entry.installPath,
-				scope: entry.scope || "user",
-			});
+		} else {
+			warnings.push(`Failed to parse OMP plugin registry: ${ompRegistryPath}`);
 		}
 	}
 
+	// Merge --plugin-dir roots (highest precedence) on every fresh load
+	if (injectedPluginDirRoots.length > 0) {
+		const injectedIds = new Set(injectedPluginDirRoots.map(r => r.id));
+		const filtered = roots.filter(r => !injectedIds.has(r.id));
+		roots.length = 0;
+		roots.push(...injectedPluginDirRoots, ...filtered);
+	}
+
 	const result = { roots, warnings };
 	pluginRootsCache.set(home, result);
 	return result;
@@ -712,4 +764,79 @@ export async function listClaudePluginRoots(home: string): Promise<{ roots: Clau
  */
 export function clearClaudePluginRootsCache(): void {
 	pluginRootsCache.clear();
+	preloadedPluginRoots = [...injectedPluginDirRoots];
+	// Re-warm preloaded roots asynchronously so sync LSP config reads stay valid
+	if (lastPreloadHome) {
+		void preloadPluginRoots(lastPreloadHome);
+	}
+}
+
+// ── Preloaded plugin roots (for sync consumers like LSP config) ─────────────
+// Populated at startup by preloadPluginRoots(). Read synchronously by
+// getPreloadedPluginRoots(). Safe degradation: empty array if not warmed.
+
+let preloadedPluginRoots: ClaudePluginRoot[] = [];
+let injectedPluginDirRoots: ClaudePluginRoot[] = [];
+let lastPreloadHome: string | undefined;
+
+/**
+ * Populate the module-level plugin roots cache for sync consumers.
+ * Call during session initialization, after dir resolution completes
+ * but before any LSP config is read.
+ */
+export async function preloadPluginRoots(home: string): Promise<void> {
+	lastPreloadHome = home;
+	const { roots } = await listClaudePluginRoots(home);
+	preloadedPluginRoots = roots;
+}
+
+/**
+ * Get pre-loaded plugin roots synchronously.
+ * Returns empty array if preloadPluginRoots() hasn't been called.
+ */
+export function getPreloadedPluginRoots(): readonly ClaudePluginRoot[] {
+	return preloadedPluginRoots;
+}
+
+// ── --plugin-dir injection ──────────────────────────────────────────────────
+
+/**
+ * Inject synthetic plugin roots from --plugin-dir paths.
+ * These are prepended to the cache with highest precedence (before OMP/Claude entries).
+ * Must be called before any listClaudePluginRoots() access.
+ */
+export async function injectPluginDirRoots(home: string, dirs: string[]): Promise<void> {
+	// Ensure the base cache is populated first
+	const { roots, warnings } = await listClaudePluginRoots(home);
+
+	const injected: ClaudePluginRoot[] = [];
+	for (const dir of dirs) {
+		const resolved = path.resolve(dir);
+		// Read plugin name from manifest
+		let pluginName = path.basename(resolved);
+		try {
+			const manifestPath = path.join(resolved, ".claude-plugin", "plugin.json");
+			const content = await Bun.file(manifestPath).text();
+			const manifest = JSON.parse(content);
+			if (typeof manifest.name === "string" && manifest.name) {
+				pluginName = manifest.name;
+			}
+		} catch {
+			// No manifest or invalid — use directory name
+		}
+
+		injected.push(buildPluginDirRoot(resolved, pluginName));
+	}
+
+	// --plugin-dir roots have highest precedence: prepend them,
+	// removing any existing entries with the same plugin ID.
+	injectedPluginDirRoots = injected;
+
+	const injectedIds = new Set(injected.map(r => r.id));
+	const filtered = roots.filter(r => !injectedIds.has(r.id));
+	const merged = [...injected, ...filtered];
+
+	// Replace the cache entry
+	pluginRootsCache.set(home, { roots: merged, warnings });
+	preloadedPluginRoots = merged;
 }

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",
+	};
+}

package/src/discovery/substitute-plugin-root.ts

@@ -0,0 +1,29 @@
+/**
+ * Recursively substitute ${CLAUDE_PLUGIN_ROOT} and ${OMP_PLUGIN_ROOT}
+ * with the actual plugin root path in strings, arrays, and plain objects.
+ */
+// Use concatenation to avoid noTemplateCurlyInString lint rule on literal placeholder names
+const CLAUDE_VAR = "$" + "{CLAUDE_PLUGIN_ROOT}";
+const OMP_VAR = "$" + "{OMP_PLUGIN_ROOT}";
+
+export function substitutePluginRoot<T>(value: T, rootPath: string): T {
+	if (typeof value === "string") {
+		return value.replaceAll(CLAUDE_VAR, rootPath).replaceAll(OMP_VAR, rootPath) as T;
+	}
+	if (Array.isArray(value)) {
+		return value.map(v => substitutePluginRoot(v, rootPath)) as T;
+	}
+	if (value && typeof value === "object") {
+		const result: Record<string, unknown> = Object.create(null);
+		for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+			Object.defineProperty(result, k, {
+				value: substitutePluginRoot(v, rootPath),
+				enumerable: true,
+				writable: true,
+				configurable: true,
+			});
+		}
+		return result as T;
+	}
+	return value;
+}

package/src/extensibility/plugins/index.ts

@@ -4,5 +4,6 @@ export * from "./doctor";
 export * from "./git-url";
 export * from "./loader";
 export * from "./manager";
+export * from "./marketplace";
 export * from "./parser";
 export type * from "./types";

package/src/extensibility/plugins/marketplace/cache.ts

@@ -0,0 +1,136 @@
+/**
+ * Plugin cache management.
+ *
+ * Cache layout: `<cacheDir>/<marketplace>___<pluginName>___<version>/`
+ *
+ * All three components are validated before any filesystem operation:
+ *   - marketplace / pluginName: isValidNameSegment (lowercase alnum + hyphens, max 64)
+ *   - version: isValidVersionForCache (alnum + ._+-, max 128)
+ *
+ * This ensures cache paths cannot be crafted to escape the cache directory.
+ */
+
+import * as nodeFs from "node:fs";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+import { isEnoent } from "@oh-my-pi/pi-utils";
+
+import { isValidNameSegment } from "./types";
+
+// Reject anything that could be used for path traversal or shell injection in
+// version strings. Only printable, unambiguous characters are allowed.
+const VERSION_RE = /^[a-zA-Z0-9._+-]+$/;
+
+/** Return true when `version` is safe for use as a cache path component. */
+export function isValidVersionForCache(version: string): boolean {
+	// prevent path-traversal sequences like ".." or "1..2"
+	return version.length > 0 && version.length <= 128 && VERSION_RE.test(version) && !version.includes("..");
+}
+
+function validateCacheComponents(marketplace: string, pluginName: string, version: string): void {
+	if (!isValidNameSegment(marketplace)) {
+		throw new Error(`Invalid marketplace name for cache: "${marketplace}"`);
+	}
+	if (!isValidNameSegment(pluginName)) {
+		throw new Error(`Invalid plugin name for cache: "${pluginName}"`);
+	}
+	if (!isValidVersionForCache(version)) {
+		throw new Error(`Invalid version for cache: "${version}"`);
+	}
+}
+
+/**
+ * Return the absolute path for a cached plugin directory.
+ * Throws if any component fails validation.
+ */
+export function getCachedPluginPath(
+	cacheDir: string,
+	marketplace: string,
+	pluginName: string,
+	version: string,
+): string {
+	validateCacheComponents(marketplace, pluginName, version);
+	return path.join(cacheDir, `${marketplace}___${pluginName}___${version}`);
+}
+
+/**
+ * Copy `sourcePath` into the cache, returning the absolute cache path.
+ *
+ * Idempotent: if the target already exists it is removed before copying,
+ * so a partial previous cache is never silently reused.
+ */
+export async function cachePlugin(
+	sourcePath: string,
+	cacheDir: string,
+	marketplace: string,
+	pluginName: string,
+	version: string,
+): Promise<string> {
+	const targetPath = getCachedPluginPath(cacheDir, marketplace, pluginName, version);
+
+	// Ensure cache directory exists before writing into it
+	await fs.mkdir(cacheDir, { recursive: true });
+
+	// Copy to a staging directory first, then atomically rename into place.
+	// This prevents destroying an active install if fs.cp fails mid-copy.
+	const stagingPath = `${targetPath}.staging-${Date.now()}`;
+	try {
+		await fs.cp(sourcePath, stagingPath, { recursive: true });
+		await fs.rm(targetPath, { recursive: true, force: true });
+		await fs.rename(stagingPath, targetPath);
+	} catch (err) {
+		// Clean up staging dir on any failure; leave existing targetPath intact
+		await fs.rm(stagingPath, { recursive: true, force: true }).catch(() => {});
+		throw err;
+	}
+
+	return targetPath;
+}
+
+/**
+ * Synchronous check — true when the cache directory exists on disk.
+ * Uses `existsSync` because callers may need to run this check inline without async.
+ */
+export function isCached(cacheDir: string, marketplace: string, pluginName: string, version: string): boolean {
+	const targetPath = getCachedPluginPath(cacheDir, marketplace, pluginName, version);
+	return nodeFs.existsSync(targetPath);
+}
+
+/** Remove a single cached plugin directory. No-op if it does not exist. */
+export async function removeCachedPlugin(
+	cacheDir: string,
+	marketplace: string,
+	pluginName: string,
+	version: string,
+): Promise<void> {
+	const targetPath = getCachedPluginPath(cacheDir, marketplace, pluginName, version);
+	await fs.rm(targetPath, { recursive: true, force: true });
+}
+
+/**
+ * Remove all cache entries whose full path is not in `installedPaths`.
+ *
+ * Returns the count of removed directories. If `cacheDir` does not exist,
+ * returns `{ removed: 0 }` rather than throwing.
+ */
+export async function cleanOrphanedCache(cacheDir: string, installedPaths: Set<string>): Promise<{ removed: number }> {
+	let entries: string[];
+	try {
+		entries = await fs.readdir(cacheDir);
+	} catch (err) {
+		if (isEnoent(err)) return { removed: 0 };
+		throw err;
+	}
+
+	let removed = 0;
+	for (const entry of entries) {
+		const fullPath = path.join(cacheDir, entry);
+		if (!installedPaths.has(fullPath)) {
+			await fs.rm(fullPath, { recursive: true, force: true });
+			removed++;
+		}
+	}
+
+	return { removed };
+}