@oh-my-pi/pi-coding-agent 1.337.0

package/src/core/plugins/doctor.ts

@@ -0,0 +1,59 @@
+import type { DoctorCheck } from "./types.js";
+
+export async function runDoctorChecks(): Promise<DoctorCheck[]> {
+	const checks: DoctorCheck[] = [];
+
+	// Check external tools
+	const tools = [
+		{ name: "fd", description: "File finder" },
+		{ name: "rg", description: "Ripgrep" },
+		{ name: "sd", description: "Find-replace" },
+		{ name: "sg", description: "AST-grep" },
+		{ name: "git", description: "Version control" },
+	];
+
+	for (const tool of tools) {
+		const path = Bun.which(tool.name);
+		checks.push({
+			name: tool.name,
+			status: path ? "ok" : "warning",
+			message: path ? `Found at ${path}` : `${tool.description} not found - some features may be limited`,
+		});
+	}
+
+	// Check API keys
+	const apiKeys = [
+		{ name: "ANTHROPIC_API_KEY", description: "Anthropic API" },
+		{ name: "OPENAI_API_KEY", description: "OpenAI API" },
+		{ name: "PERPLEXITY_API_KEY", description: "Perplexity search" },
+		{ name: "EXA_API_KEY", description: "Exa search" },
+	];
+
+	for (const key of apiKeys) {
+		const hasKey = !!process.env[key.name];
+		checks.push({
+			name: key.name,
+			status: hasKey ? "ok" : "warning",
+			message: hasKey ? "Configured" : `Not set - ${key.description} unavailable`,
+		});
+	}
+
+	return checks;
+}
+
+export function formatDoctorResults(checks: DoctorCheck[]): string {
+	const lines: string[] = ["System Health Check", "=".repeat(40), ""];
+
+	for (const check of checks) {
+		const icon = check.status === "ok" ? "✓" : check.status === "warning" ? "!" : "✗";
+		lines.push(`${icon} ${check.name}: ${check.message}`);
+	}
+
+	const errors = checks.filter((c) => c.status === "error").length;
+	const warnings = checks.filter((c) => c.status === "warning").length;
+
+	lines.push("");
+	lines.push(`Summary: ${checks.length - errors - warnings} ok, ${warnings} warnings, ${errors} errors`);
+
+	return lines.join("\n");
+}

package/src/core/plugins/index.ts

@@ -0,0 +1,38 @@
+// Plugin system exports
+export { formatDoctorResults, runDoctorChecks } from "./doctor.js";
+export {
+	getAllPluginCommandPaths,
+	getAllPluginHookPaths,
+	getAllPluginToolPaths,
+	getEnabledPlugins,
+	getPluginSettings,
+	resolvePluginCommandPaths,
+	resolvePluginHookPaths,
+	resolvePluginToolPaths,
+} from "./loader.js";
+export { PluginManager, parseSettingValue, validateSetting } from "./manager.js";
+export { extractPackageName, formatPluginSpec, parsePluginSpec } from "./parser.js";
+export {
+	getPluginsDir,
+	getPluginsLockfile,
+	getPluginsNodeModules,
+	getPluginsPackageJson,
+	getProjectPluginOverrides,
+} from "./paths.js";
+export type {
+	BooleanSetting,
+	DoctorCheck,
+	DoctorOptions,
+	EnumSetting,
+	InstalledPlugin,
+	InstallOptions,
+	NumberSetting,
+	PluginFeature,
+	PluginManifest,
+	PluginRuntimeConfig,
+	PluginRuntimeState,
+	PluginSettingSchema,
+	PluginSettingType,
+	ProjectPluginOverrides,
+	StringSetting,
+} from "./types.js";

package/src/core/plugins/installer.ts

@@ -0,0 +1,189 @@
+import { mkdir } from "fs/promises";
+import { join, resolve } from "path";
+import { getAgentDir } from "../../config.js";
+import type { InstalledPlugin } from "./types.js";
+
+const PLUGINS_DIR = join(getAgentDir(), "plugins");
+
+// Valid npm package name pattern (scoped and unscoped)
+const VALID_PACKAGE_NAME = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*(@[a-z0-9-._^~>=<]+)?$/i;
+
+/**
+ * Validate package name to prevent command injection
+ */
+function validatePackageName(name: string): void {
+	if (!VALID_PACKAGE_NAME.test(name)) {
+		throw new Error(`Invalid package name: ${name}`);
+	}
+	// Extra safety: no shell metacharacters
+	if (/[;&|`$(){}[\]<>\\]/.test(name)) {
+		throw new Error(`Invalid characters in package name: ${name}`);
+	}
+}
+
+/**
+ * Ensure the plugins directory exists
+ */
+async function ensurePluginsDir(): Promise<void> {
+	await mkdir(PLUGINS_DIR, { recursive: true });
+	await mkdir(join(PLUGINS_DIR, "node_modules"), { recursive: true });
+}
+
+export async function installPlugin(packageName: string): Promise<InstalledPlugin> {
+	// Validate package name to prevent command injection
+	validatePackageName(packageName);
+
+	// Ensure plugins directory exists
+	await ensurePluginsDir();
+
+	// Initialize package.json if it doesn't exist
+	const pkgJsonPath = join(PLUGINS_DIR, "package.json");
+	if (!(await Bun.file(pkgJsonPath).exists())) {
+		await Bun.write(pkgJsonPath, JSON.stringify({ name: "pi-plugins", private: true, dependencies: {} }, null, 2));
+	}
+
+	// Run npm install in plugins directory
+	const proc = Bun.spawn(["npm", "install", packageName], {
+		cwd: PLUGINS_DIR,
+		stdin: "ignore",
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+
+	const exitCode = await proc.exited;
+	if (exitCode !== 0) {
+		const stderr = await new Response(proc.stderr).text();
+		throw new Error(`Failed to install ${packageName}: ${stderr}`);
+	}
+
+	// Extract the actual package name (without version specifier) for path lookup
+	const actualName = packageName.replace(/@[^/]+$/, "").replace(/^(@[^/]+\/[^@]+).*$/, "$1");
+
+	// Read the installed package's package.json
+	const pkgPath = join(PLUGINS_DIR, "node_modules", actualName, "package.json");
+	const pkgFile = Bun.file(pkgPath);
+	if (!(await pkgFile.exists())) {
+		throw new Error(`Package installed but package.json not found at ${pkgPath}`);
+	}
+
+	const pkg = await pkgFile.json();
+
+	return {
+		name: pkg.name,
+		version: pkg.version,
+		path: join(PLUGINS_DIR, "node_modules", actualName),
+		manifest: pkg.omp || pkg.pi || { version: pkg.version },
+		enabledFeatures: null,
+		enabled: true,
+	};
+}
+
+export async function uninstallPlugin(name: string): Promise<void> {
+	// Validate package name
+	validatePackageName(name);
+
+	await ensurePluginsDir();
+
+	const proc = Bun.spawn(["npm", "uninstall", name], {
+		cwd: PLUGINS_DIR,
+		stdin: "ignore",
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+
+	const exitCode = await proc.exited;
+	if (exitCode !== 0) {
+		throw new Error(`Failed to uninstall ${name}`);
+	}
+}
+
+export async function listPlugins(): Promise<InstalledPlugin[]> {
+	const pkgJsonPath = join(PLUGINS_DIR, "package.json");
+	if (!(await Bun.file(pkgJsonPath).exists())) {
+		return [];
+	}
+
+	const pkg = await Bun.file(pkgJsonPath).json();
+	const deps = pkg.dependencies || {};
+
+	const plugins: InstalledPlugin[] = [];
+	for (const [name, _version] of Object.entries(deps)) {
+		const pluginPkgPath = join(PLUGINS_DIR, "node_modules", name, "package.json");
+		if (await Bun.file(pluginPkgPath).exists()) {
+			const pluginPkg = await Bun.file(pluginPkgPath).json();
+			plugins.push({
+				name,
+				version: pluginPkg.version,
+				path: join(PLUGINS_DIR, "node_modules", name),
+				manifest: pluginPkg.omp || pluginPkg.pi || { version: pluginPkg.version },
+				enabledFeatures: null,
+				enabled: true,
+			});
+		}
+	}
+
+	return plugins;
+}
+
+export async function linkPlugin(localPath: string): Promise<void> {
+	const cwd = process.cwd();
+	const absolutePath = resolve(cwd, localPath);
+
+	// Validate that resolved path is within cwd to prevent path traversal
+	const normalizedCwd = resolve(cwd);
+	const normalizedPath = resolve(absolutePath);
+	if (!normalizedPath.startsWith(`${normalizedCwd}/`) && normalizedPath !== normalizedCwd) {
+		throw new Error(`Invalid path: ${localPath} resolves outside working directory`);
+	}
+
+	// Validate package.json exists
+	const pkgFile = Bun.file(join(absolutePath, "package.json"));
+	if (!(await pkgFile.exists())) {
+		throw new Error(`package.json not found at ${absolutePath}`);
+	}
+
+	let pkg: { name?: string };
+	try {
+		pkg = await pkgFile.json();
+	} catch (err) {
+		throw new Error(`Invalid package.json at ${absolutePath}: ${err}`);
+	}
+
+	if (!pkg.name || typeof pkg.name !== "string") {
+		throw new Error("package.json must have a valid name field");
+	}
+
+	// Validate package name to prevent path traversal via pkg.name
+	if (pkg.name.includes("..") || pkg.name.includes("/") || pkg.name.includes("\\")) {
+		// Exception: scoped packages have one slash
+		if (!pkg.name.startsWith("@") || (pkg.name.match(/\//g) || []).length !== 1) {
+			throw new Error(`Invalid package name in package.json: ${pkg.name}`);
+		}
+	}
+
+	await ensurePluginsDir();
+
+	// Create symlink in plugins/node_modules
+	const linkPath = join(PLUGINS_DIR, "node_modules", pkg.name);
+
+	// For scoped packages, ensure the scope directory exists
+	if (pkg.name.startsWith("@")) {
+		const scopeDir = join(PLUGINS_DIR, "node_modules", pkg.name.split("/")[0]);
+		await mkdir(scopeDir, { recursive: true });
+	}
+
+	// Remove existing if present
+	try {
+		const { unlinkSync, lstatSync } = await import("fs");
+		const stat = lstatSync(linkPath);
+		if (stat.isSymbolicLink() || stat.isDirectory()) {
+			unlinkSync(linkPath);
+		}
+	} catch {
+		// Doesn't exist, that's fine
+	}
+
+	// Create symlink using fs instead of shell command
+	const { symlinkSync } = await import("fs");
+	symlinkSync(absolutePath, linkPath);
+}

package/src/core/plugins/loader.ts

@@ -0,0 +1,338 @@
+/**
+ * Plugin loader - discovers and loads tools/hooks from installed plugins.
+ *
+ * Reads enabled plugins from the runtime config and loads their tools/hooks
+ * based on manifest entries and enabled features.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import {
+	getPluginsLockfile,
+	getPluginsNodeModules,
+	getPluginsPackageJson,
+	getProjectPluginOverrides,
+} from "./paths.js";
+import type { InstalledPlugin, PluginManifest, PluginRuntimeConfig, ProjectPluginOverrides } from "./types.js";
+
+// =============================================================================
+// Runtime Config Loading
+// =============================================================================
+
+/**
+ * Load plugin runtime config from lock file.
+ */
+function loadRuntimeConfig(): PluginRuntimeConfig {
+	const lockPath = getPluginsLockfile();
+	if (!existsSync(lockPath)) {
+		return { plugins: {}, settings: {} };
+	}
+	try {
+		return JSON.parse(readFileSync(lockPath, "utf-8"));
+	} catch {
+		return { plugins: {}, settings: {} };
+	}
+}
+
+/**
+ * Load project-local plugin overrides.
+ */
+function loadProjectOverrides(cwd: string): ProjectPluginOverrides {
+	const overridesPath = getProjectPluginOverrides(cwd);
+	if (!existsSync(overridesPath)) {
+		return {};
+	}
+	try {
+		return JSON.parse(readFileSync(overridesPath, "utf-8"));
+	} catch {
+		return {};
+	}
+}
+
+// =============================================================================
+// Plugin Discovery
+// =============================================================================
+
+/**
+ * Get list of enabled plugins with their resolved configurations.
+ * Respects both global runtime config and project overrides.
+ */
+export function getEnabledPlugins(cwd: string): InstalledPlugin[] {
+	const pkgJsonPath = getPluginsPackageJson();
+	if (!existsSync(pkgJsonPath)) {
+		return [];
+	}
+
+	const nodeModulesPath = getPluginsNodeModules();
+	if (!existsSync(nodeModulesPath)) {
+		return [];
+	}
+
+	const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+	const deps = pkg.dependencies || {};
+	const runtimeConfig = loadRuntimeConfig();
+	const projectOverrides = loadProjectOverrides(cwd);
+	const plugins: InstalledPlugin[] = [];
+
+	for (const [name] of Object.entries(deps)) {
+		const pluginPkgPath = join(nodeModulesPath, name, "package.json");
+		if (!existsSync(pluginPkgPath)) {
+			continue;
+		}
+
+		const pluginPkg = JSON.parse(readFileSync(pluginPkgPath, "utf-8"));
+		const manifest: PluginManifest | undefined = pluginPkg.omp || pluginPkg.pi;
+
+		if (!manifest) {
+			// Not a pi plugin, skip
+			continue;
+		}
+
+		manifest.version = pluginPkg.version;
+
+		const runtimeState = runtimeConfig.plugins[name];
+
+		// Check if disabled globally
+		if (runtimeState && !runtimeState.enabled) {
+			continue;
+		}
+
+		// Check if disabled in project
+		if (projectOverrides.disabled?.includes(name)) {
+			continue;
+		}
+
+		// Resolve enabled features (project overrides take precedence)
+		const enabledFeatures = projectOverrides.features?.[name] ?? runtimeState?.enabledFeatures ?? null;
+
+		plugins.push({
+			name,
+			version: pluginPkg.version,
+			path: join(nodeModulesPath, name),
+			manifest,
+			enabledFeatures,
+			enabled: true,
+		});
+	}
+
+	return plugins;
+}
+
+// =============================================================================
+// Path Resolution
+// =============================================================================
+
+/**
+ * Resolve tool entry points for a plugin based on manifest and enabled features.
+ * Returns absolute paths to tool modules.
+ */
+export function resolvePluginToolPaths(plugin: InstalledPlugin): string[] {
+	const paths: string[] = [];
+	const manifest = plugin.manifest;
+
+	// Base tools entry (always included if exists)
+	if (manifest.tools) {
+		const toolPath = join(plugin.path, manifest.tools);
+		if (existsSync(toolPath)) {
+			paths.push(toolPath);
+		}
+	}
+
+	// Feature-specific tools
+	if (manifest.features && plugin.enabledFeatures) {
+		const enabledSet = new Set(plugin.enabledFeatures);
+
+		for (const [featName, feat] of Object.entries(manifest.features)) {
+			if (!enabledSet.has(featName)) continue;
+
+			if (feat.tools) {
+				for (const toolEntry of feat.tools) {
+					const toolPath = join(plugin.path, toolEntry);
+					if (existsSync(toolPath)) {
+						paths.push(toolPath);
+					}
+				}
+			}
+		}
+	} else if (manifest.features && plugin.enabledFeatures === null) {
+		// null means use defaults - enable features with default: true
+		for (const [_featName, feat] of Object.entries(manifest.features)) {
+			if (!feat.default) continue;
+
+			if (feat.tools) {
+				for (const toolEntry of feat.tools) {
+					const toolPath = join(plugin.path, toolEntry);
+					if (existsSync(toolPath)) {
+						paths.push(toolPath);
+					}
+				}
+			}
+		}
+	}
+
+	return paths;
+}
+
+/**
+ * Resolve hook entry points for a plugin based on manifest and enabled features.
+ * Returns absolute paths to hook modules.
+ */
+export function resolvePluginHookPaths(plugin: InstalledPlugin): string[] {
+	const paths: string[] = [];
+	const manifest = plugin.manifest;
+
+	// Base hooks entry (always included if exists)
+	if (manifest.hooks) {
+		const hookPath = join(plugin.path, manifest.hooks);
+		if (existsSync(hookPath)) {
+			paths.push(hookPath);
+		}
+	}
+
+	// Feature-specific hooks
+	if (manifest.features && plugin.enabledFeatures) {
+		const enabledSet = new Set(plugin.enabledFeatures);
+
+		for (const [featName, feat] of Object.entries(manifest.features)) {
+			if (!enabledSet.has(featName)) continue;
+
+			if (feat.hooks) {
+				for (const hookEntry of feat.hooks) {
+					const hookPath = join(plugin.path, hookEntry);
+					if (existsSync(hookPath)) {
+						paths.push(hookPath);
+					}
+				}
+			}
+		}
+	} else if (manifest.features && plugin.enabledFeatures === null) {
+		// null means use defaults - enable features with default: true
+		for (const [_featName, feat] of Object.entries(manifest.features)) {
+			if (!feat.default) continue;
+
+			if (feat.hooks) {
+				for (const hookEntry of feat.hooks) {
+					const hookPath = join(plugin.path, hookEntry);
+					if (existsSync(hookPath)) {
+						paths.push(hookPath);
+					}
+				}
+			}
+		}
+	}
+
+	return paths;
+}
+
+/**
+ * Resolve command file paths for a plugin based on manifest and enabled features.
+ * Returns absolute paths to command files (.md).
+ */
+export function resolvePluginCommandPaths(plugin: InstalledPlugin): string[] {
+	const paths: string[] = [];
+	const manifest = plugin.manifest;
+
+	// Base commands (always included if exists)
+	if (manifest.commands) {
+		for (const cmdEntry of manifest.commands) {
+			const cmdPath = join(plugin.path, cmdEntry);
+			if (existsSync(cmdPath)) {
+				paths.push(cmdPath);
+			}
+		}
+	}
+
+	// Feature-specific commands
+	if (manifest.features && plugin.enabledFeatures) {
+		const enabledSet = new Set(plugin.enabledFeatures);
+
+		for (const [featName, feat] of Object.entries(manifest.features)) {
+			if (!enabledSet.has(featName)) continue;
+
+			if (feat.commands) {
+				for (const cmdEntry of feat.commands) {
+					const cmdPath = join(plugin.path, cmdEntry);
+					if (existsSync(cmdPath)) {
+						paths.push(cmdPath);
+					}
+				}
+			}
+		}
+	} else if (manifest.features && plugin.enabledFeatures === null) {
+		// null means use defaults - enable features with default: true
+		for (const [_featName, feat] of Object.entries(manifest.features)) {
+			if (!feat.default) continue;
+
+			if (feat.commands) {
+				for (const cmdEntry of feat.commands) {
+					const cmdPath = join(plugin.path, cmdEntry);
+					if (existsSync(cmdPath)) {
+						paths.push(cmdPath);
+					}
+				}
+			}
+		}
+	}
+
+	return paths;
+}
+
+// =============================================================================
+// Aggregated Discovery
+// =============================================================================
+
+/**
+ * Get all tool paths from all enabled plugins.
+ */
+export function getAllPluginToolPaths(cwd: string): string[] {
+	const plugins = getEnabledPlugins(cwd);
+	const paths: string[] = [];
+
+	for (const plugin of plugins) {
+		paths.push(...resolvePluginToolPaths(plugin));
+	}
+
+	return paths;
+}
+
+/**
+ * Get all hook paths from all enabled plugins.
+ */
+export function getAllPluginHookPaths(cwd: string): string[] {
+	const plugins = getEnabledPlugins(cwd);
+	const paths: string[] = [];
+
+	for (const plugin of plugins) {
+		paths.push(...resolvePluginHookPaths(plugin));
+	}
+
+	return paths;
+}
+
+/**
+ * Get all command paths from all enabled plugins.
+ */
+export function getAllPluginCommandPaths(cwd: string): string[] {
+	const plugins = getEnabledPlugins(cwd);
+	const paths: string[] = [];
+
+	for (const plugin of plugins) {
+		paths.push(...resolvePluginCommandPaths(plugin));
+	}
+
+	return paths;
+}
+
+/**
+ * Get plugin settings for use in tool/hook contexts.
+ * Merges global settings with project overrides.
+ */
+export function getPluginSettings(pluginName: string, cwd: string): Record<string, unknown> {
+	const runtimeConfig = loadRuntimeConfig();
+	const projectOverrides = loadProjectOverrides(cwd);
+
+	const global = runtimeConfig.settings[pluginName] || {};
+	const project = projectOverrides.settings?.[pluginName] || {};
+
+	return { ...global, ...project };
+}