@oh-my-pi/cli 0.1.0 → 0.3.0

package/src/manifest.ts

@@ -3,11 +3,21 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import {
 	GLOBAL_PACKAGE_JSON,
-	LEGACY_MANIFEST_PATH,
 	NODE_MODULES_DIR,
 	PLUGINS_DIR,
+	PROJECT_PACKAGE_JSON,
 	PROJECT_PLUGINS_JSON,
-} from "./paths.js";
+} from "@omp/paths";
+
+/**
+ * Format permission-related errors with actionable guidance
+ */
+function formatPermissionError(err: NodeJS.ErrnoException, path: string): string {
+	if (err.code === "EACCES" || err.code === "EPERM") {
+		return `Permission denied: Cannot write to ${path}. Check directory permissions or run with appropriate privileges.`;
+	}
+	return err.message;
+}
 
 /**
  * OMP field in package.json - defines what files to install
@@ -15,10 +25,51 @@ import {
 export interface OmpInstallEntry {
 	src: string;
 	dest: string;
+	/** If true, this file is copied (not symlinked) and can be edited by omp */
+	copy?: boolean;
+}
+
+/**
+ * Runtime configuration stored in plugin's runtime.json
+ * This file is copied (not symlinked) and edited by omp features/config commands
+ */
+export interface PluginRuntimeConfig {
+	features?: string[];
+	options?: Record<string, unknown>;
+}
+
+/**
+ * Runtime variable definition with type, default, and metadata
+ */
+export interface OmpVariable {
+	type: "string" | "number" | "boolean" | "string[]";
+	default?: string | number | boolean | string[];
+	description?: string;
+	required?: boolean;
+	/** Environment variable name if injected as env (e.g., "EXA_API_KEY") */
+	env?: string;
+}
+
+/**
+ * Feature definition - metadata only, no install entries
+ * All feature files are always installed; runtime.json controls which are active
+ */
+export interface OmpFeature {
+	description?: string;
+	/** Runtime variables specific to this feature */
+	variables?: Record<string, OmpVariable>;
+	/** Default enabled state (default: true) */
+	default?: boolean;
 }
 
 export interface OmpField {
+	/** Top-level install entries (always installed, not feature-gated) */
 	install?: OmpInstallEntry[];
+	/** Top-level runtime variables (always available) */
+	variables?: Record<string, OmpVariable>;
+	/** Named features with their own install entries and variables */
+	features?: Record<string, OmpFeature>;
+	/** Disabled state (managed by omp, not plugin author) */
 	disabled?: boolean;
 }
 
@@ -36,48 +87,92 @@ export interface PluginPackageJson {
 	files?: string[];
 }
 
+/**
+ * Per-plugin configuration stored in plugins.json
+ */
+export interface PluginConfig {
+	/**
+	 * Enabled feature names:
+	 * - null/undefined: use plugin defaults (first install = all, reinstall = preserve)
+	 * - ["*"]: explicitly all features
+	 * - []: no optional features (core only)
+	 * - ["f1", "f2"]: specific features
+	 */
+	features?: string[] | null;
+	/** Runtime variable overrides */
+	variables?: Record<string, string | number | boolean | string[]>;
+}
+
 /**
  * Global/project plugins.json structure
  */
 export interface PluginsJson {
 	plugins: Record<string, string>; // name -> version specifier
+	devDependencies?: Record<string, string>; // dev dependencies
 	disabled?: string[]; // disabled plugin names
+	/** Per-plugin feature and variable config */
+	config?: Record<string, PluginConfig>;
 }
 
 /**
- * Legacy manifest structure (for migration)
+ * Initialize the global plugins directory with package.json
  */
-export interface LegacyPluginInfo {
-	type: "github" | "local" | "npm";
-	repo?: string;
-	package?: string;
-	path?: string;
-	subdir?: string;
-	version?: string;
-	linked?: boolean;
-	installed: string[];
-	installedAt: string;
-}
+export async function initGlobalPlugins(): Promise<void> {
+	try {
+		await mkdir(PLUGINS_DIR, { recursive: true });
 
-export interface LegacyManifest {
-	plugins: Record<string, LegacyPluginInfo>;
+		if (!existsSync(GLOBAL_PACKAGE_JSON)) {
+			const packageJson = {
+				name: "pi-plugins",
+				version: "1.0.0",
+				private: true,
+				description: "Global pi plugins managed by omp",
+				dependencies: {},
+			};
+			await writeFile(GLOBAL_PACKAGE_JSON, JSON.stringify(packageJson, null, 2));
+		}
+	} catch (err) {
+		const error = err as NodeJS.ErrnoException;
+		if (error.code === "EACCES" || error.code === "EPERM") {
+			throw new Error(formatPermissionError(error, PLUGINS_DIR));
+		}
+		throw err;
+	}
 }
 
 /**
- * Initialize the global plugins directory with package.json
+ * Initialize the project-local .pi directory with plugins.json and package.json
  */
-export async function initGlobalPlugins(): Promise<void> {
-	await mkdir(PLUGINS_DIR, { recursive: true });
+export async function initProjectPlugins(): Promise<void> {
+	const PROJECT_PI_DIR = dirname(PROJECT_PLUGINS_JSON);
+	try {
+		await mkdir(PROJECT_PI_DIR, { recursive: true });
 
-	if (!existsSync(GLOBAL_PACKAGE_JSON)) {
-		const packageJson = {
-			name: "pi-plugins",
-			version: "1.0.0",
-			private: true,
-			description: "Global pi plugins managed by omp",
-			dependencies: {},
-		};
-		await writeFile(GLOBAL_PACKAGE_JSON, JSON.stringify(packageJson, null, 2));
+		// Create plugins.json if it doesn't exist
+		if (!existsSync(PROJECT_PLUGINS_JSON)) {
+			const pluginsJson = {
+				plugins: {},
+			};
+			await writeFile(PROJECT_PLUGINS_JSON, JSON.stringify(pluginsJson, null, 2));
+		}
+
+		// Create package.json if it doesn't exist (for npm operations)
+		if (!existsSync(PROJECT_PACKAGE_JSON)) {
+			const packageJson = {
+				name: "pi-project-plugins",
+				version: "1.0.0",
+				private: true,
+				description: "Project-local pi plugins managed by omp",
+				dependencies: {},
+			};
+			await writeFile(PROJECT_PACKAGE_JSON, JSON.stringify(packageJson, null, 2));
+		}
+	} catch (err) {
+		const error = err as NodeJS.ErrnoException;
+		if (error.code === "EACCES" || error.code === "EPERM") {
+			throw new Error(formatPermissionError(error, PROJECT_PI_DIR));
+		}
+		throw err;
 	}
 }
 
@@ -95,53 +190,125 @@ export async function loadPluginsJson(global = true): Promise<PluginsJson> {
 			// Global uses standard package.json format
 			return {
 				plugins: parsed.dependencies || {},
+				devDependencies: parsed.devDependencies || {},
 				disabled: parsed.omp?.disabled || [],
+				config: parsed.omp?.config || {},
 			};
 		}
 
 		// Project uses plugins.json format
 		return {
 			plugins: parsed.plugins || {},
+			devDependencies: parsed.devDependencies || {},
 			disabled: parsed.disabled || [],
+			config: parsed.config || {},
 		};
 	} catch (err) {
 		if ((err as NodeJS.ErrnoException).code === "ENOENT") {
-			return { plugins: {}, disabled: [] };
+			return { plugins: {}, devDependencies: {}, disabled: [], config: {} };
 		}
 		throw err;
 	}
 }
 
+/**
+ * Sync .pi/package.json with plugins.json for npm operations in project-local mode
+ */
+async function syncProjectPackageJson(data: PluginsJson): Promise<void> {
+	let existing: Record<string, unknown> = {};
+	try {
+		existing = JSON.parse(await readFile(PROJECT_PACKAGE_JSON, "utf-8"));
+	} catch {
+		existing = {
+			name: "pi-project-plugins",
+			version: "1.0.0",
+			private: true,
+			description: "Project-local pi plugins managed by omp",
+		};
+	}
+
+	existing.dependencies = data.plugins;
+	if (data.devDependencies && Object.keys(data.devDependencies).length > 0) {
+		existing.devDependencies = data.devDependencies;
+	} else {
+		delete existing.devDependencies;
+	}
+
+	await writeFile(PROJECT_PACKAGE_JSON, JSON.stringify(existing, null, 2));
+}
+
 /**
  * Save plugins.json (global or project)
  */
 export async function savePluginsJson(data: PluginsJson, global = true): Promise<void> {
 	const path = global ? GLOBAL_PACKAGE_JSON : PROJECT_PLUGINS_JSON;
-	await mkdir(dirname(path), { recursive: true });
-
-	if (global) {
-		// Read existing package.json and update dependencies
-		let existing: Record<string, unknown> = {};
-		try {
-			existing = JSON.parse(await readFile(path, "utf-8"));
-		} catch {
-			existing = {
-				name: "pi-plugins",
-				version: "1.0.0",
-				private: true,
-				description: "Global pi plugins managed by omp",
-			};
-		}
 
-		existing.dependencies = data.plugins;
-		if (data.disabled?.length) {
-			existing.omp = { ...((existing.omp as Record<string, unknown>) || {}), disabled: data.disabled };
-		}
+	try {
+		await mkdir(dirname(path), { recursive: true });
 
-		await writeFile(path, JSON.stringify(existing, null, 2));
-	} else {
-		// Project uses simple plugins.json format
-		await writeFile(path, JSON.stringify(data, null, 2));
+		if (global) {
+			// Read existing package.json and update dependencies
+			let existing: Record<string, unknown> = {};
+			try {
+				existing = JSON.parse(await readFile(path, "utf-8"));
+			} catch {
+				existing = {
+					name: "pi-plugins",
+					version: "1.0.0",
+					private: true,
+					description: "Global pi plugins managed by omp",
+				};
+			}
+
+			existing.dependencies = data.plugins;
+			if (data.devDependencies && Object.keys(data.devDependencies).length > 0) {
+				existing.devDependencies = data.devDependencies;
+			} else {
+				delete existing.devDependencies;
+			}
+
+			// Build omp field with disabled and config
+			const ompField: Record<string, unknown> = (existing.omp as Record<string, unknown>) || {};
+			if (data.disabled?.length) {
+				ompField.disabled = data.disabled;
+			} else {
+				delete ompField.disabled;
+			}
+			if (data.config && Object.keys(data.config).length > 0) {
+				ompField.config = data.config;
+			} else {
+				delete ompField.config;
+			}
+			if (Object.keys(ompField).length > 0) {
+				existing.omp = ompField;
+			} else {
+				delete existing.omp;
+			}
+
+			await writeFile(path, JSON.stringify(existing, null, 2));
+		} else {
+			// Project uses simple plugins.json format
+			const output: Record<string, unknown> = { plugins: data.plugins };
+			if (data.devDependencies && Object.keys(data.devDependencies).length > 0) {
+				output.devDependencies = data.devDependencies;
+			}
+			if (data.disabled?.length) {
+				output.disabled = data.disabled;
+			}
+			if (data.config && Object.keys(data.config).length > 0) {
+				output.config = data.config;
+			}
+			await writeFile(path, JSON.stringify(output, null, 2));
+
+			// Sync .pi/package.json for npm operations
+			await syncProjectPackageJson(data);
+		}
+	} catch (err) {
+		const error = err as NodeJS.ErrnoException;
+		if (error.code === "EACCES" || error.code === "EPERM") {
+			throw new Error(formatPermissionError(error, path));
+		}
+		throw err;
 	}
 }
 
@@ -175,25 +342,6 @@ export function getPluginSourceDir(pluginName: string, global = true): string {
 	return join(nodeModules, pluginName);
 }
 
-/**
- * Check if legacy manifest.json exists
- */
-export function hasLegacyManifest(): boolean {
-	return existsSync(LEGACY_MANIFEST_PATH);
-}
-
-/**
- * Load legacy manifest.json
- */
-export async function loadLegacyManifest(): Promise<LegacyManifest> {
-	try {
-		const data = await readFile(LEGACY_MANIFEST_PATH, "utf-8");
-		return JSON.parse(data) as LegacyManifest;
-	} catch {
-		return { plugins: {} };
-	}
-}
-
 /**
  * Get all installed plugins with their info
  */

package/src/npm.ts

@@ -1,4 +1,40 @@
-import { execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
+import type { OmpField } from "@omp/manifest";
+
+export interface NpmAvailability {
+	available: boolean;
+	version?: string;
+	error?: string;
+}
+
+/**
+ * Check npm availability and version
+ */
+export function checkNpmAvailable(): NpmAvailability {
+	try {
+		const version = execFileSync("npm", ["--version"], {
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+		}).trim();
+
+		// Parse version and check minimum (npm 7+)
+		const major = parseInt(version.split(".")[0], 10);
+		if (major < 7) {
+			return {
+				available: false,
+				version,
+				error: `npm version ${version} is too old. Please upgrade to npm 7 or later.`,
+			};
+		}
+
+		return { available: true, version };
+	} catch {
+		return {
+			available: false,
+			error: "npm is not installed or not in PATH. Please install Node.js/npm.",
+		};
+	}
+}
 
 export interface NpmPackageInfo {
 	name: string;
@@ -10,6 +46,8 @@ export interface NpmPackageInfo {
 	repository?: { type: string; url: string } | string;
 	versions?: string[];
 	"dist-tags"?: Record<string, string>;
+	omp?: OmpField;
+	dependencies?: Record<string, string>;
 }
 
 export interface NpmSearchResult {
@@ -21,23 +59,45 @@ export interface NpmSearchResult {
 	author?: { name: string };
 }
 
+const DEFAULT_TIMEOUT_MS = 60000; // 60 seconds
+
 /**
  * Execute npm command and return output
  */
-export function npmExec(args: string[], cwd?: string): string {
-	const cmd = `npm ${args.join(" ")}`;
-	return execSync(cmd, {
-		cwd,
-		stdio: ["pipe", "pipe", "pipe"],
-		encoding: "utf-8",
-	});
+export function npmExec(args: string[], cwd?: string, timeout = DEFAULT_TIMEOUT_MS): string {
+	try {
+		return execFileSync("npm", args, {
+			cwd,
+			stdio: ["pipe", "pipe", "pipe"],
+			encoding: "utf-8",
+			timeout,
+		});
+	} catch (err) {
+		const error = err as { killed?: boolean; code?: string; message: string };
+		if (error.killed || error.code === "ETIMEDOUT") {
+			throw new Error(`npm operation timed out after ${timeout / 1000} seconds`);
+		}
+		throw err;
+	}
 }
 
 /**
  * Execute npm command with prefix (for installing to specific directory)
  */
-export function npmExecWithPrefix(args: string[], prefix: string): string {
-	return npmExec(["--prefix", prefix, ...args]);
+export function npmExecWithPrefix(args: string[], prefix: string, timeout = DEFAULT_TIMEOUT_MS): string {
+	try {
+		return execFileSync("npm", ["--prefix", prefix, ...args], {
+			stdio: ["pipe", "pipe", "pipe"],
+			encoding: "utf-8",
+			timeout,
+		});
+	} catch (err) {
+		const error = err as { killed?: boolean; code?: string; message: string };
+		if (error.killed || error.code === "ETIMEDOUT") {
+			throw new Error(`npm operation timed out after ${timeout / 1000} seconds`);
+		}
+		throw err;
+	}
 }
 
 /**
@@ -84,14 +144,10 @@ export async function npmInfo(packageName: string): Promise<NpmPackageInfo | nul
  * Search npm for packages with a keyword
  */
 export async function npmSearch(query: string, keyword = "omp-plugin"): Promise<NpmSearchResult[]> {
-	try {
-		// Search for packages with the omp-plugin keyword
-		const searchTerm = keyword ? `keywords:${keyword} ${query}` : query;
-		const output = npmExec(["search", searchTerm, "--json"]);
-		return JSON.parse(output);
-	} catch {
-		return [];
-	}
+	// Search for packages with the omp-plugin keyword
+	const searchTerm = keyword ? `keywords:${keyword} ${query}` : query;
+	const output = npmExec(["search", searchTerm, "--json"]);
+	return JSON.parse(output);
 }
 
 /**

package/src/paths.ts

@@ -1,5 +1,6 @@
+import { existsSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 
 // Global pi configuration directory
 export const PI_CONFIG_DIR = join(homedir(), ".pi");
@@ -16,15 +17,15 @@ export const GLOBAL_PACKAGE_JSON = join(PLUGINS_DIR, "package.json");
 // Global package-lock.json
 export const GLOBAL_LOCK_FILE = join(PLUGINS_DIR, "package-lock.json");
 
-// Legacy manifest (for migration)
-export const LEGACY_MANIFEST_PATH = join(PLUGINS_DIR, "manifest.json");
-
 // Project-local config directory
 export const PROJECT_PI_DIR = ".pi";
 
 // Project-local plugins.json
 export const PROJECT_PLUGINS_JSON = join(PROJECT_PI_DIR, "plugins.json");
 
+// Project-local package.json (for npm operations)
+export const PROJECT_PACKAGE_JSON = join(PROJECT_PI_DIR, "package.json");
+
 // Project-local lock file
 export const PROJECT_PLUGINS_LOCK = join(PROJECT_PI_DIR, "plugins-lock.json");
 
@@ -32,13 +33,45 @@ export const PROJECT_PLUGINS_LOCK = join(PROJECT_PI_DIR, "plugins-lock.json");
 export const PROJECT_NODE_MODULES = join(PROJECT_PI_DIR, "node_modules");
 
 /**
- * Get the agent directory (where symlinks are installed)
+ * Find the project root by walking up parent directories looking for .pi/plugins.json.
+ * Similar to how git finds .git directories.
+ *
+ * @returns The absolute path to the project root, or null if not found
  */
-export function getAgentDir(global = true): string {
-	if (global) {
-		return join(PI_CONFIG_DIR, "agent");
+export function findProjectRoot(): string | null {
+	let dir = process.cwd();
+	const root = resolve("/");
+
+	while (dir !== root) {
+		if (existsSync(join(dir, ".pi", "plugins.json"))) {
+			return dir;
+		}
+		const parent = dirname(dir);
+		if (parent === dir) break; // Reached filesystem root
+		dir = parent;
+	}
+
+	return null;
+}
+
+/**
+ * Check if a project-local .pi/plugins.json exists in the current directory or any parent
+ */
+export function hasProjectPlugins(): boolean {
+	return findProjectRoot() !== null;
+}
+
+/**
+ * Get the project .pi directory path.
+ * Uses findProjectRoot() to locate the project, or falls back to cwd.
+ */
+export function getProjectPiDir(): string {
+	const projectRoot = findProjectRoot();
+	if (projectRoot) {
+		return join(projectRoot, ".pi");
 	}
-	return join(PROJECT_PI_DIR, "agent");
+	// Fallback to cwd (e.g., for init command)
+	return resolve(PROJECT_PI_DIR);
 }
 
 /**
@@ -48,7 +81,7 @@ export function getPluginsDir(global = true): string {
 	if (global) {
 		return PLUGINS_DIR;
 	}
-	return PROJECT_PI_DIR;
+	return getProjectPiDir();
 }
 
 /**
@@ -58,7 +91,7 @@ export function getNodeModulesDir(global = true): string {
 	if (global) {
 		return NODE_MODULES_DIR;
 	}
-	return PROJECT_NODE_MODULES;
+	return join(getProjectPiDir(), "node_modules");
 }
 
 /**
@@ -68,5 +101,37 @@ export function getPackageJsonPath(global = true): string {
 	if (global) {
 		return GLOBAL_PACKAGE_JSON;
 	}
-	return PROJECT_PLUGINS_JSON;
+	return join(getProjectPiDir(), "plugins.json");
+}
+
+/**
+ * Get the agent directory (where symlinks are installed)
+ */
+export function getAgentDir(global = true): string {
+	if (global) {
+		return join(PI_CONFIG_DIR, "agent");
+	}
+	return join(getProjectPiDir(), "agent");
+}
+
+/**
+ * Resolve whether to use global or local scope based on CLI flags and auto-detection.
+ *
+ * Logic:
+ * - If --global is passed: use global mode
+ * - If --local is passed: use local mode
+ * - If neither: check if .pi/plugins.json exists in cwd, if so use local, otherwise use global
+ *
+ * @param options - CLI options containing global and local flags
+ * @returns true if global scope should be used, false for local
+ */
+export function resolveScope(options: { global?: boolean; local?: boolean }): boolean {
+	if (options.global) {
+		return true;
+	}
+	if (options.local) {
+		return false;
+	}
+	// Auto-detect: if project-local plugins.json exists, use local mode
+	return !hasProjectPlugins();
 }