@oh-my-pi/pi-coding-agent 15.5.11 → 15.5.12

package/src/discovery/omp-plugins.ts

@@ -0,0 +1,383 @@
+/**
+ * OMP extension-package sub-discovery provider.
+ *
+ * When a user configures an extension via `extensions:` (in settings) or
+ * `--extension`/`-e` (on the CLI), the docs promise that the package's
+ * sibling directories — `skills/`, `hooks/pre|post/`, `tools/`, `commands/`,
+ * `rules/`, `prompts/`, and `.mcp.json` — are picked up by omp's standard
+ * discovery surfaces. The native `omp` provider in `builtin.ts` only walks
+ * `.omp/` and `~/.omp/agent/`, so without this provider those sub-trees are
+ * silently ignored.
+ *
+ * Provider priority is set below the native `omp` provider (100) so an
+ * extension package never shadows the user's own `.omp/` configuration on
+ * dedup.
+ *
+ * @see ./omp-extension-roots.ts
+ * @see ../../docs/extension-loading.md
+ */
+import * as path from "node:path";
+import { logger, parseFrontmatter, tryParseJson } from "@oh-my-pi/pi-utils";
+import { registerProvider } from "../capability";
+import { readDirEntries, readFile } from "../capability/fs";
+import { type Hook, hookCapability } from "../capability/hook";
+import { type MCPServer, mcpCapability } from "../capability/mcp";
+import { type Prompt, promptCapability } from "../capability/prompt";
+import { type Rule, ruleCapability } from "../capability/rule";
+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 { buildRuleFromMarkdown, createSourceMeta, loadFilesFromDir, scanSkillsFromDir } from "./helpers";
+import { listOmpExtensionRoots, type OmpExtensionRoot } from "./omp-extension-roots";
+
+const PROVIDER_ID = "omp-plugins";
+const DISPLAY_NAME = "OMP Extension Packages";
+const DESCRIPTION =
+	"Sub-discovery (skills, hooks, tools, commands, rules, prompts, .mcp.json) inside extension packages";
+const PRIORITY = 90;
+
+// =============================================================================
+// Skills
+// =============================================================================
+
+async function loadSkills(ctx: LoadContext): Promise<LoadResult<Skill>> {
+	const roots = await listOmpExtensionRoots(ctx);
+	const results = await Promise.all(
+		roots.map(root =>
+			scanSkillsFromDir(ctx, {
+				dir: path.join(root.path, "skills"),
+				providerId: PROVIDER_ID,
+				level: root.level,
+				requireDescription: true,
+			}),
+		),
+	);
+	return {
+		items: results.flatMap(r => r.items),
+		warnings: results.flatMap(r => r.warnings ?? []),
+	};
+}
+
+// =============================================================================
+// Slash Commands
+// =============================================================================
+
+async function loadSlashCommands(ctx: LoadContext): Promise<LoadResult<SlashCommand>> {
+	const roots = await listOmpExtensionRoots(ctx);
+	const results = await Promise.all(
+		roots.map(root =>
+			loadFilesFromDir<SlashCommand>(ctx, path.join(root.path, "commands"), PROVIDER_ID, root.level, {
+				extensions: ["md"],
+				transform: (name, content, filePath, source) => ({
+					name: name.replace(/\.md$/, ""),
+					path: filePath,
+					content,
+					level: root.level,
+					_source: source,
+				}),
+			}),
+		),
+	);
+	return {
+		items: results.flatMap(r => r.items),
+		warnings: results.flatMap(r => r.warnings ?? []),
+	};
+}
+
+// =============================================================================
+// Rules
+// =============================================================================
+
+async function loadRules(ctx: LoadContext): Promise<LoadResult<Rule>> {
+	const roots = await listOmpExtensionRoots(ctx);
+	const results = await Promise.all(
+		roots.map(root =>
+			loadFilesFromDir<Rule>(ctx, path.join(root.path, "rules"), PROVIDER_ID, root.level, {
+				extensions: ["md", "mdc"],
+				transform: (name, content, filePath, source) =>
+					buildRuleFromMarkdown(name, content, filePath, source, { stripNamePattern: /\.(md|mdc)$/ }),
+			}),
+		),
+	);
+	return {
+		items: results.flatMap(r => r.items),
+		warnings: results.flatMap(r => r.warnings ?? []),
+	};
+}
+
+// =============================================================================
+// Prompts
+// =============================================================================
+
+async function loadPrompts(ctx: LoadContext): Promise<LoadResult<Prompt>> {
+	const roots = await listOmpExtensionRoots(ctx);
+	const results = await Promise.all(
+		roots.map(root =>
+			loadFilesFromDir<Prompt>(ctx, path.join(root.path, "prompts"), PROVIDER_ID, root.level, {
+				extensions: ["md"],
+				transform: (name, content, filePath, source) => ({
+					name: name.replace(/\.md$/, ""),
+					path: filePath,
+					content,
+					_source: source,
+				}),
+			}),
+		),
+	);
+	return {
+		items: results.flatMap(r => r.items),
+		warnings: results.flatMap(r => r.warnings ?? []),
+	};
+}
+
+// =============================================================================
+// Hooks
+// =============================================================================
+
+const HOOK_TYPES: ReadonlyArray<"pre" | "post"> = ["pre", "post"];
+
+async function loadHooks(ctx: LoadContext): Promise<LoadResult<Hook>> {
+	const roots = await listOmpExtensionRoots(ctx);
+	const tasks: Array<{ root: OmpExtensionRoot; hookType: "pre" | "post" }> = [];
+	for (const root of roots) {
+		for (const hookType of HOOK_TYPES) {
+			tasks.push({ root, hookType });
+		}
+	}
+	const results = await Promise.all(
+		tasks.map(({ root, hookType }) =>
+			loadFilesFromDir<Hook>(ctx, path.join(root.path, "hooks", hookType), PROVIDER_ID, root.level, {
+				transform: (name, _content, filePath, source) => {
+					const baseName = name.includes(".") ? name.slice(0, name.lastIndexOf(".")) : name;
+					const tool = baseName === "*" ? "*" : baseName;
+					return {
+						name,
+						path: filePath,
+						type: hookType,
+						tool,
+						level: root.level,
+						_source: source,
+					};
+				},
+			}),
+		),
+	);
+	return {
+		items: results.flatMap(r => r.items),
+		warnings: results.flatMap(r => r.warnings ?? []),
+	};
+}
+
+// =============================================================================
+// Custom Tools
+// =============================================================================
+
+const TOOL_EXTENSIONS = ["json", "md", "ts", "js", "sh", "bash", "py"];
+
+async function loadTools(ctx: LoadContext): Promise<LoadResult<CustomTool>> {
+	const roots = await listOmpExtensionRoots(ctx);
+	const perRoot = await Promise.all(
+		roots.map(async root => {
+			const toolsDir = path.join(root.path, "tools");
+			const [filesResult, entries] = await Promise.all([
+				loadFilesFromDir<CustomTool>(ctx, toolsDir, PROVIDER_ID, root.level, {
+					extensions: TOOL_EXTENSIONS,
+					transform: (name, content, filePath, source) => {
+						if (name.endsWith(".json")) {
+							const data = tryParseJson<{ name?: string; description?: string }>(content);
+							const toolName = data?.name || name.replace(/\.json$/, "");
+							const description =
+								typeof data?.description === "string" && data.description.trim()
+									? data.description
+									: `${toolName} custom tool`;
+							return { name: toolName, path: filePath, description, level: root.level, _source: source };
+						}
+						if (name.endsWith(".md")) {
+							const { frontmatter } = parseFrontmatter(content, { source: filePath });
+							const toolName = (frontmatter.name as string) || name.replace(/\.md$/, "");
+							const description =
+								typeof frontmatter.description === "string" && frontmatter.description.trim()
+									? String(frontmatter.description)
+									: `${toolName} custom tool`;
+							return { name: toolName, path: filePath, description, level: root.level, _source: source };
+						}
+						const toolName = name.replace(/\.(ts|js|sh|bash|py)$/, "");
+						return {
+							name: toolName,
+							path: filePath,
+							description: `${toolName} custom tool`,
+							level: root.level,
+							_source: source,
+						};
+					},
+				}),
+				readDirEntries(toolsDir),
+			]);
+
+			// `<tools>/<name>/index.ts` sub-directory tools, mirroring `builtin.ts:loadTools`.
+			const indexCandidates = entries
+				.filter(e => !e.name.startsWith(".") && e.isDirectory())
+				.map(e => path.join(toolsDir, e.name, "index.ts"));
+			const indexContents = await Promise.all(indexCandidates.map(p => readFile(p)));
+			const indexItems: CustomTool[] = [];
+			for (let i = 0; i < indexCandidates.length; i++) {
+				if (indexContents[i] === null) continue;
+				const indexPath = indexCandidates[i];
+				const toolName = path.basename(path.dirname(indexPath));
+				indexItems.push({
+					name: toolName,
+					path: indexPath,
+					description: `${toolName} custom tool`,
+					level: root.level,
+					_source: createSourceMeta(PROVIDER_ID, indexPath, root.level),
+				});
+			}
+
+			return { filesResult, indexItems };
+		}),
+	);
+
+	const items: CustomTool[] = [];
+	const warnings: string[] = [];
+	for (const { filesResult, indexItems } of perRoot) {
+		items.push(...filesResult.items, ...indexItems);
+		if (filesResult.warnings) warnings.push(...filesResult.warnings);
+	}
+	return { items, warnings };
+}
+
+// =============================================================================
+// MCP Servers
+// =============================================================================
+
+const MCP_FILENAMES = [".mcp.json", "mcp.json"] as const;
+
+interface RawMcpServer {
+	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?: MCPServer["transport"];
+}
+
+async function loadMCPServers(ctx: LoadContext): Promise<LoadResult<MCPServer>> {
+	const roots = await listOmpExtensionRoots(ctx);
+	const items: MCPServer[] = [];
+	const warnings: string[] = [];
+
+	const tasks: Array<{ root: OmpExtensionRoot; mcpPath: string }> = [];
+	for (const root of roots) {
+		for (const filename of MCP_FILENAMES) {
+			tasks.push({ root, mcpPath: path.join(root.path, filename) });
+		}
+	}
+	const contents = await Promise.all(tasks.map(({ mcpPath }) => readFile(mcpPath)));
+
+	for (let i = 0; i < tasks.length; i++) {
+		const raw = contents[i];
+		if (raw === null) continue;
+		const { root, mcpPath } = tasks[i];
+
+		const parsed = tryParseJson<{ mcpServers?: Record<string, unknown> }>(raw);
+		if (!parsed) {
+			warnings.push(`[omp-plugins] Invalid JSON in ${mcpPath}`);
+			logger.warn(`[omp-plugins] Invalid JSON in ${mcpPath}`);
+			continue;
+		}
+		const servers = parsed.mcpServers;
+		if (!servers || typeof servers !== "object" || Array.isArray(servers)) continue;
+
+		for (const [serverName, serverCfg] of Object.entries(servers)) {
+			if (!serverCfg || typeof serverCfg !== "object" || Array.isArray(serverCfg)) continue;
+			const cfg = serverCfg as RawMcpServer;
+			if (typeof cfg.command !== "string" && typeof cfg.url !== "string") {
+				warnings.push(`[omp-plugins] Skipping MCP server "${serverName}" in ${mcpPath}: missing command or url`);
+				continue;
+			}
+			items.push({
+				name: serverName,
+				...(cfg.enabled !== undefined && { enabled: cfg.enabled }),
+				...(cfg.timeout !== undefined && { timeout: cfg.timeout }),
+				...(cfg.command !== undefined && { command: cfg.command }),
+				...(cfg.args !== undefined && { args: cfg.args }),
+				...(cfg.env !== undefined && { env: cfg.env }),
+				...(cfg.cwd !== undefined && { cwd: cfg.cwd }),
+				...(cfg.url !== undefined && { url: cfg.url }),
+				...(cfg.headers !== undefined && { headers: cfg.headers }),
+				...(cfg.auth !== undefined && { auth: cfg.auth }),
+				...(cfg.oauth !== undefined && { oauth: cfg.oauth }),
+				...(cfg.type !== undefined && { transport: cfg.type }),
+				_source: createSourceMeta(PROVIDER_ID, mcpPath, root.level),
+			});
+		}
+	}
+
+	return { items, warnings };
+}
+
+// =============================================================================
+// Provider Registration
+// =============================================================================
+
+registerProvider<Skill>(skillCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: DESCRIPTION,
+	priority: PRIORITY,
+	load: loadSkills,
+});
+
+registerProvider<SlashCommand>(slashCommandCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: DESCRIPTION,
+	priority: PRIORITY,
+	load: loadSlashCommands,
+});
+
+registerProvider<Rule>(ruleCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: DESCRIPTION,
+	priority: PRIORITY,
+	load: loadRules,
+});
+
+registerProvider<Prompt>(promptCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: DESCRIPTION,
+	priority: PRIORITY,
+	load: loadPrompts,
+});
+
+registerProvider<Hook>(hookCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: DESCRIPTION,
+	priority: PRIORITY,
+	load: loadHooks,
+});
+
+registerProvider<CustomTool>(toolCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: DESCRIPTION,
+	priority: PRIORITY,
+	load: loadTools,
+});
+
+registerProvider<MCPServer>(mcpCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: DESCRIPTION,
+	priority: PRIORITY,
+	load: loadMCPServers,
+});

package/src/extensibility/plugins/loader.ts

@@ -19,9 +19,14 @@ installLegacyPiSpecifierShim();
 
 /**
  * Load plugin runtime config from lock file.
+ *
+ * `home` controls which `<plugins>/omp-plugins.lock.json` is read — pass it
+ * through whenever the caller is loading plugins for a tempdir-rooted
+ * scenario (tests, discovery sub-surfaces that need to mirror an alternate
+ * `LoadContext.home`).
  */
-async function loadRuntimeConfig(): Promise<PluginRuntimeConfig> {
-	const lockPath = getPluginsLockfile();
+async function loadRuntimeConfig(home?: string): Promise<PluginRuntimeConfig> {
+	const lockPath = getPluginsLockfile(home);
 	try {
 		return await Bun.file(lockPath).json();
 	} catch (err) {
@@ -46,44 +51,64 @@ async function loadProjectOverrides(cwd: string): Promise<ProjectPluginOverrides
 }
 /**
  * Get list of enabled plugins with their resolved configurations.
- * Respects both global runtime config and project overrides.
+ *
+ * Respects both global runtime config and project overrides. Iterates the
+ * union of `<plugins>/package.json#dependencies` (`bun install`-installed
+ * packages) and `<plugins>/omp-plugins.lock.json#plugins` (so locally
+ * `plugin link`-symlinked extensions, which never get a dependency entry,
+ * are still discovered). The optional `home` parameter pins the plugins
+ * root for callers that need to enumerate plugins relative to a non-default
+ * home (tests with a tempdir, discovery loaders threaded with
+ * `LoadContext.home`).
  */
-export async function getEnabledPlugins(cwd: string): Promise<InstalledPlugin[]> {
-	const pkgJsonPath = getPluginsPackageJson();
-	let pkg: { dependencies?: Record<string, string> };
-	try {
-		pkg = await Bun.file(pkgJsonPath).json();
-	} catch (err) {
-		if (isEnoent(err)) return [];
-		throw err;
-	}
+export async function getEnabledPlugins(cwd: string, opts: { home?: string } = {}): Promise<InstalledPlugin[]> {
+	const { home } = opts;
 
-	const nodeModulesPath = getPluginsNodeModules();
+	const nodeModulesPath = getPluginsNodeModules(home);
 	if (!fs.existsSync(nodeModulesPath)) {
 		return [];
 	}
 
-	const deps = pkg.dependencies || {};
-	const runtimeConfig = await loadRuntimeConfig();
+	let depsKeys: string[] = [];
+	const pkgJsonPath = getPluginsPackageJson(home);
+	try {
+		const pkg: { dependencies?: Record<string, string> } = await Bun.file(pkgJsonPath).json();
+		depsKeys = Object.keys(pkg.dependencies ?? {});
+	} catch (err) {
+		// Linked-only setups may have no `<plugins>/package.json` yet — that's
+		// fine, the lockfile still records the link.
+		if (!isEnoent(err)) throw err;
+	}
+
+	const runtimeConfig = await loadRuntimeConfig(home);
 	const projectOverrides = await loadProjectOverrides(cwd);
+
+	// Union: dependencies (npm/marketplace installs) ∪ runtime-config plugins
+	// (links + already-recorded installs). Set preserves first-seen order,
+	// putting deps before link-only entries for deterministic output.
+	const names = new Set<string>(depsKeys);
+	for (const name of Object.keys(runtimeConfig.plugins ?? {})) {
+		names.add(name);
+	}
+
 	const plugins: InstalledPlugin[] = [];
-	for (const [name] of Object.entries(deps)) {
+	for (const name of names) {
 		const pluginPkgPath = path.join(nodeModulesPath, name, "package.json");
 		let pluginPkg: { version: string; omp?: PluginManifest; pi?: PluginManifest };
 		try {
 			pluginPkg = await Bun.file(pluginPkgPath).json();
 		} catch (err) {
+			// Lockfile entry without a corresponding node_modules tree means the
+			// link was deleted out from under us; skip silently.
 			if (isEnoent(err)) continue;
 			throw err;
 		}
 
 		const manifest: PluginManifest | undefined = pluginPkg.omp || pluginPkg.pi;
-
 		if (!manifest) {
 			// Not an omp plugin, skip
 			continue;
 		}
-
 		manifest.version = pluginPkg.version;
 
 		const runtimeState = runtimeConfig.plugins[name];

package/src/main.ts

@@ -36,6 +36,7 @@ import {
 	preloadPluginRoots,
 	resolveActiveProjectRegistryPath,
 } from "./discovery/helpers";
+import { injectOmpExtensionCliRoots } from "./discovery/omp-extension-roots";
 import { exportFromFile } from "./export/html";
 import type { ExtensionUIContext } from "./extensibility/extensions/types";
 import {
@@ -768,6 +769,17 @@ export async function runRootCommand(
 	// warning before we reach the await site below.
 	pluginPreloadPromise.catch(() => {});
 
+	// Register CLI-provided extension package paths (`--extension`, `--hook`) so
+	// the `omp-plugins` discovery provider can surface their `skills/`, `hooks/`,
+	// `tools/`, `commands/`, `rules/`, `prompts/`, and `.mcp.json` sub-trees.
+	// `--no-extensions` short-circuits both the factory load and the sub-discovery.
+	if (!parsedArgs.noExtensions) {
+		const cliExtensions = [...(parsedArgs.extensions ?? []), ...(parsedArgs.hooks ?? [])];
+		if (cliExtensions.length > 0) {
+			injectOmpExtensionCliRoots(cliExtensions, home, getProjectDir());
+		}
+	}
+
 	const cwd = getProjectDir();
 	const settingsInstance = deps.settings ?? (await logger.time("settings:init", Settings.init, { cwd }));
 	if (parsedArgs.approvalMode) {