@oh-my-pi/cli 0.1.0 → 0.2.0

package/src/lockfile.ts

@@ -0,0 +1,132 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { GLOBAL_LOCK_FILE, PROJECT_PLUGINS_LOCK } from "@omp/paths";
+import chalk from "chalk";
+
+/**
+ * Lock file schema version
+ */
+export const LOCKFILE_VERSION = 1;
+
+/**
+ * Package entry in the lock file
+ */
+export interface LockFilePackage {
+	version: string;
+	resolved?: string;
+	integrity?: string;
+	dependencies?: Record<string, string>;
+}
+
+/**
+ * Lock file structure
+ */
+export interface LockFile {
+	lockfileVersion: number;
+	packages: Record<string, LockFilePackage>;
+}
+
+/**
+ * Load and validate a lock file.
+ *
+ * Returns null if:
+ * - File doesn't exist
+ * - File contains invalid JSON (corrupted)
+ * - File has invalid/incompatible schema
+ */
+export async function loadLockFile(global = true): Promise<LockFile | null> {
+	const path = global ? GLOBAL_LOCK_FILE : PROJECT_PLUGINS_LOCK;
+	try {
+		if (!existsSync(path)) return null;
+		const data = await readFile(path, "utf-8");
+		const parsed = JSON.parse(data);
+
+		// Validate schema
+		if (typeof parsed.lockfileVersion !== "number" || typeof parsed.packages !== "object") {
+			console.log(chalk.yellow(`Warning: ${path} has invalid schema, ignoring`));
+			return null;
+		}
+
+		// Check for incompatible version
+		if (parsed.lockfileVersion > LOCKFILE_VERSION) {
+			console.log(
+				chalk.yellow(
+					`Warning: ${path} was created by a newer version of omp (lockfile v${parsed.lockfileVersion}), ignoring`,
+				),
+			);
+			return null;
+		}
+
+		return parsed as LockFile;
+	} catch (err) {
+		if ((err as Error).name === "SyntaxError") {
+			console.log(chalk.yellow(`Warning: ${path} is corrupted (invalid JSON), ignoring`));
+		}
+		return null;
+	}
+}
+
+/**
+ * Save lock file
+ */
+export async function saveLockFile(lockFile: LockFile, global = true): Promise<void> {
+	const path = global ? GLOBAL_LOCK_FILE : PROJECT_PLUGINS_LOCK;
+	await writeFile(path, JSON.stringify(lockFile, null, 2));
+}
+
+/**
+ * Create a new empty lock file
+ */
+export function createLockFile(): LockFile {
+	return {
+		lockfileVersion: LOCKFILE_VERSION,
+		packages: {},
+	};
+}
+
+/**
+ * Validate and optionally regenerate a corrupted lock file.
+ *
+ * @returns The loaded lock file, a new empty lock file if corrupted/missing, or null if validation fails
+ */
+export async function validateOrRegenerateLockFile(global = true): Promise<LockFile> {
+	const existing = await loadLockFile(global);
+	if (existing) {
+		return existing;
+	}
+
+	// Lock file is missing or corrupted - create a fresh one
+	const path = global ? GLOBAL_LOCK_FILE : PROJECT_PLUGINS_LOCK;
+	if (existsSync(path)) {
+		console.log(chalk.yellow(`Regenerating corrupted lock file: ${path}`));
+	}
+
+	return createLockFile();
+}
+
+/**
+ * Get the locked version for a package, if it exists in the lock file.
+ */
+export async function getLockedVersion(packageName: string, global = true): Promise<string | null> {
+	const lockFile = await loadLockFile(global);
+	if (!lockFile) return null;
+
+	const entry = lockFile.packages[packageName];
+	return entry?.version ?? null;
+}
+
+/**
+ * Update the lock file with a package's exact version.
+ */
+export async function updateLockFile(packageName: string, version: string, global = true): Promise<void> {
+	let lockFile = await loadLockFile(global);
+	if (!lockFile) {
+		lockFile = createLockFile();
+	}
+
+	lockFile.packages[packageName] = {
+		version,
+	};
+
+	await saveLockFile(lockFile, global);
+}

package/src/manifest.ts

@@ -6,8 +6,19 @@ import {
 	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
@@ -41,6 +52,7 @@ export interface PluginPackageJson {
  */
 export interface PluginsJson {
 	plugins: Record<string, string>; // name -> version specifier
+	devDependencies?: Record<string, string>; // dev dependencies
 	disabled?: string[]; // disabled plugin names
 }
 
@@ -67,17 +79,61 @@ export interface LegacyManifest {
  * Initialize the global plugins directory with package.json
  */
 export async function initGlobalPlugins(): Promise<void> {
-	await mkdir(PLUGINS_DIR, { recursive: true });
+	try {
+		await mkdir(PLUGINS_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));
+		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 project-local .pi directory with plugins.json and package.json
+ */
+export async function initProjectPlugins(): Promise<void> {
+	const PROJECT_PI_DIR = dirname(PROJECT_PLUGINS_JSON);
+	try {
+		await mkdir(PROJECT_PI_DIR, { recursive: true });
+
+		// 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,6 +151,7 @@ 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 || [],
 			};
 		}
@@ -102,46 +159,97 @@ export async function loadPluginsJson(global = true): Promise<PluginsJson> {
 		// Project uses plugins.json format
 		return {
 			plugins: parsed.plugins || {},
+			devDependencies: parsed.devDependencies || {},
 			disabled: parsed.disabled || [],
 		};
 	} catch (err) {
 		if ((err as NodeJS.ErrnoException).code === "ENOENT") {
-			return { plugins: {}, disabled: [] };
+			return { plugins: {}, devDependencies: {}, disabled: [] };
 		}
 		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;
+			}
+			if (data.disabled?.length) {
+				existing.omp = { ...((existing.omp as Record<string, unknown>) || {}), disabled: data.disabled };
+			}
+
+			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;
+			}
+			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;
 	}
 }
 

package/src/migrate.ts

@@ -2,16 +2,18 @@ import { existsSync } from "node:fs";
 import { mkdir, readFile, rename, rm, symlink, writeFile } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { createInterface } from "node:readline";
-import chalk from "chalk";
 import {
 	hasLegacyManifest,
 	type LegacyPluginInfo,
 	loadLegacyManifest,
 	type PluginPackageJson,
 	type PluginsJson,
+	readPluginPackageJson,
 	savePluginsJson,
-} from "./manifest.js";
-import { LEGACY_MANIFEST_PATH, NODE_MODULES_DIR, PLUGINS_DIR } from "./paths.js";
+} from "@omp/manifest";
+import { LEGACY_MANIFEST_PATH, NODE_MODULES_DIR, PLUGINS_DIR } from "@omp/paths";
+import { createPluginSymlinks } from "@omp/symlinks";
+import chalk from "chalk";
 
 /**
  * Prompt user for migration
@@ -104,6 +106,15 @@ export async function migrateToNpm(): Promise<boolean> {
 		// Archive legacy manifest
 		await archiveLegacyManifest();
 
+		// Re-create symlinks for migrated plugins
+		console.log(chalk.dim("  Creating symlinks..."));
+		for (const [name] of Object.entries(newPluginsJson.plugins)) {
+			const pkgJson = await readPluginPackageJson(name, true); // global mode
+			if (pkgJson?.omp?.install?.length) {
+				await createPluginSymlinks(name, pkgJson, true);
+			}
+		}
+
 		console.log();
 		console.log(chalk.green(`✓ Migrated ${migrated.length} plugin(s)`));
 		if (failed.length > 0) {

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");
@@ -25,6 +26,9 @@ 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 +36,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 +84,7 @@ export function getPluginsDir(global = true): string {
 	if (global) {
 		return PLUGINS_DIR;
 	}
-	return PROJECT_PI_DIR;
+	return getProjectPiDir();
 }
 
 /**
@@ -58,7 +94,7 @@ export function getNodeModulesDir(global = true): string {
 	if (global) {
 		return NODE_MODULES_DIR;
 	}
-	return PROJECT_NODE_MODULES;
+	return join(getProjectPiDir(), "node_modules");
 }
 
 /**
@@ -68,5 +104,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();
 }