@oh-my-pi/cli 0.1.0 → 0.2.0

package/src/cli.ts

@@ -1,22 +1,32 @@
 #!/usr/bin/env bun
 
+import { createPlugin } from "@omp/commands/create";
+import { runDoctor } from "@omp/commands/doctor";
+import { disablePlugin, enablePlugin } from "@omp/commands/enable";
+import { showInfo } from "@omp/commands/info";
+import { initProject } from "@omp/commands/init";
+import { installPlugin } from "@omp/commands/install";
+import { linkPlugin } from "@omp/commands/link";
+import { listPlugins } from "@omp/commands/list";
+import { showOutdated } from "@omp/commands/outdated";
+import { searchPlugins } from "@omp/commands/search";
+import { uninstallPlugin } from "@omp/commands/uninstall";
+import { updatePlugin } from "@omp/commands/update";
+import { whyFile } from "@omp/commands/why";
+import { withErrorHandling } from "@omp/errors";
+import { checkMigration, migrateToNpm } from "@omp/migrate";
+import { checkNpmAvailable } from "@omp/npm";
+import chalk from "chalk";
 import { program } from "commander";
-import { createPlugin } from "./commands/create.js";
-import { runDoctor } from "./commands/doctor.js";
-import { disablePlugin, enablePlugin } from "./commands/enable.js";
-import { showInfo } from "./commands/info.js";
-import { initProject } from "./commands/init.js";
-import { installPlugin } from "./commands/install.js";
-import { linkPlugin } from "./commands/link.js";
-import { listPlugins } from "./commands/list.js";
-import { showOutdated } from "./commands/outdated.js";
-import { searchPlugins } from "./commands/search.js";
-import { uninstallPlugin } from "./commands/uninstall.js";
-import { updatePlugin } from "./commands/update.js";
-import { whyFile } from "./commands/why.js";
-import { checkMigration, migrateToNpm } from "./migrate.js";
-
-program.name("omp").description("Oh My Pi - Plugin manager for pi configuration").version("0.1.0");
+
+// Check npm availability at startup
+const npmCheck = checkNpmAvailable();
+if (!npmCheck.available) {
+	console.log(chalk.red(npmCheck.error));
+	process.exit(1);
+}
+
+program.name("omp").description("Oh My Pi - Plugin manager for pi configuration").version("0.2.0");
 
 // Check for migration on startup (only for commands that need it)
 program.hook("preAction", async (thisCommand) => {
@@ -45,36 +55,40 @@ Examples:
   $ omp install                         # Install all from plugins.json
 `,
 	)
-	.option("-g, --global", "Install globally to ~/.pi (default)")
+	.option("-g, --global", "Install globally to ~/.pi")
+	.option("-l, --local", "Install to project-local .pi/")
 	.option("-S, --save", "Add to plugins.json")
 	.option("-D, --save-dev", "Add as dev dependency")
 	.option("--force", "Overwrite conflicts without prompting")
 	.option("--json", "Output as JSON")
-	.action(installPlugin);
+	.action(withErrorHandling(installPlugin));
 
 program
 	.command("uninstall <name>")
 	.alias("rm")
 	.description("Remove plugin and its symlinks")
-	.option("-g, --global", "Uninstall from ~/.pi (default)")
+	.option("-g, --global", "Uninstall from ~/.pi")
+	.option("-l, --local", "Uninstall from project-local .pi/")
 	.option("--json", "Output as JSON")
-	.action(uninstallPlugin);
+	.action(withErrorHandling(uninstallPlugin));
 
 program
 	.command("update [name]")
 	.alias("up")
 	.description("Update to latest within semver range")
-	.option("-g, --global", "Update global plugins (default)")
+	.option("-g, --global", "Update global plugins")
+	.option("-l, --local", "Update project-local plugins")
 	.option("--json", "Output as JSON")
-	.action(updatePlugin);
+	.action(withErrorHandling(updatePlugin));
 
 program
 	.command("list")
 	.alias("ls")
 	.description("Show installed plugins")
-	.option("-g, --global", "List global plugins (default)")
+	.option("-g, --global", "List global plugins")
+	.option("-l, --local", "List project-local plugins")
 	.option("--json", "Output as JSON")
-	.action(listPlugins);
+	.action(withErrorHandling(listPlugins));
 
 program
 	.command("link <path>")
@@ -87,8 +101,10 @@ so changes are reflected immediately without reinstalling.
 `,
 	)
 	.option("-n, --name <name>", "Custom name for the plugin")
-	.option("-g, --global", "Link globally (default)")
-	.action(linkPlugin);
+	.option("-g, --global", "Link globally")
+	.option("-l, --local", "Link to project-local .pi/")
+	.option("--force", "Overwrite existing npm-installed plugin")
+	.action(withErrorHandling(linkPlugin));
 
 // ============================================================================
 // New Commands
@@ -98,70 +114,80 @@ program
 	.command("init")
 	.description("Create .pi/plugins.json in current project")
 	.option("--force", "Overwrite existing plugins.json")
-	.action(initProject);
+	.action(withErrorHandling(initProject));
 
 program
 	.command("search <query>")
 	.description("Search npm for omp-plugin keyword")
 	.option("--json", "Output as JSON")
 	.option("--limit <n>", "Maximum results to show", "20")
-	.action((query, options) => searchPlugins(query, { ...options, limit: parseInt(options.limit, 10) }));
+	.action(
+		withErrorHandling((query, options) => searchPlugins(query, { ...options, limit: parseInt(options.limit, 10) })),
+	);
 
 program
 	.command("info <package>")
 	.description("Show plugin details before install")
 	.option("--json", "Output as JSON")
 	.option("--versions", "Show available versions")
-	.action(showInfo);
+	.option("--all-versions", "Show all published versions")
+	.action(withErrorHandling(showInfo));
 
 program
 	.command("outdated")
 	.description("List plugins with newer versions")
-	.option("-g, --global", "Check global plugins (default)")
+	.option("-g, --global", "Check global plugins")
+	.option("-l, --local", "Check project-local plugins")
 	.option("--json", "Output as JSON")
-	.action(showOutdated);
+	.action(withErrorHandling(showOutdated));
 
 program
 	.command("doctor")
 	.description("Check for broken symlinks, conflicts")
-	.option("-g, --global", "Check global plugins (default)")
+	.option("-g, --global", "Check global plugins")
+	.option("-l, --local", "Check project-local plugins")
 	.option("--fix", "Attempt to fix issues")
 	.option("--json", "Output as JSON")
-	.action(runDoctor);
+	.action(withErrorHandling(runDoctor));
 
 program
 	.command("create <name>")
 	.description("Scaffold new plugin from template")
 	.option("-d, --description <desc>", "Plugin description")
 	.option("-a, --author <author>", "Plugin author")
-	.action(createPlugin);
+	.action(withErrorHandling(createPlugin));
 
 program
 	.command("why <file>")
 	.description("Show which plugin installed a file")
-	.option("-g, --global", "Check global plugins (default)")
+	.option("-g, --global", "Check global plugins")
+	.option("-l, --local", "Check project-local plugins")
 	.option("--json", "Output as JSON")
-	.action(whyFile);
+	.action(withErrorHandling(whyFile));
 
 program
 	.command("enable <name>")
 	.description("Enable a disabled plugin")
-	.option("-g, --global", "Target global plugins (default)")
+	.option("-g, --global", "Target global plugins")
+	.option("-l, --local", "Target project-local plugins")
 	.option("--json", "Output as JSON")
-	.action(enablePlugin);
+	.action(withErrorHandling(enablePlugin));
 
 program
 	.command("disable <name>")
 	.description("Disable plugin without uninstalling")
-	.option("-g, --global", "Target global plugins (default)")
+	.option("-g, --global", "Target global plugins")
+	.option("-l, --local", "Target project-local plugins")
 	.option("--json", "Output as JSON")
-	.action(disablePlugin);
+	.action(withErrorHandling(disablePlugin));
 
 program
 	.command("migrate")
 	.description("Migrate from legacy manifest.json to npm-native format")
-	.action(async () => {
-		await migrateToNpm();
-	});
+	.action(
+		withErrorHandling(async () => {
+			await migrateToNpm();
+		}),
+	);
 
 program.parse();

package/src/commands/create.ts

@@ -8,16 +8,65 @@ export interface CreateOptions {
 	author?: string;
 }
 
+const VALID_NPM_CHARS = new Set("abcdefghijklmnopqrstuvwxyz0123456789-_.");
+
+/**
+ * Validate that a name conforms to npm naming rules
+ */
+function isValidNpmName(name: string): boolean {
+	if (!name || name.length === 0) return false;
+	if (name.startsWith(".") || name.startsWith("_")) return false;
+	if (name.includes(" ")) return false;
+	for (const char of name) {
+		if (!VALID_NPM_CHARS.has(char)) return false;
+	}
+	return true;
+}
+
+/**
+ * Normalize a string to be a valid npm package name
+ */
+function normalizePluginName(name: string): string {
+	let normalized = name.toLowerCase().split(" ").join("-");
+
+	// Remove invalid characters (keep alphanumeric, -, _, .)
+	normalized = Array.from(normalized)
+		.filter((char) => VALID_NPM_CHARS.has(char))
+		.join("");
+
+	// Can't start with . or _ or -
+	while (normalized.startsWith(".") || normalized.startsWith("_") || normalized.startsWith("-")) {
+		normalized = normalized.slice(1);
+	}
+
+	return normalized;
+}
+
 /**
  * Scaffold a new plugin from template
  */
 export async function createPlugin(name: string, options: CreateOptions = {}): Promise<void> {
 	// Ensure name follows conventions
-	const pluginName = name.startsWith("omp-") ? name : `omp-${name}`;
+	let pluginName = name.startsWith("omp-") ? name : `omp-${name}`;
+
+	// Validate and normalize the plugin name
+	if (!isValidNpmName(pluginName)) {
+		const normalized = normalizePluginName(pluginName);
+		if (!normalized || normalized === "omp-" || normalized === "omp") {
+			console.log(chalk.red(`Error: Invalid plugin name "${name}" cannot be normalized to a valid npm name`));
+			process.exitCode = 1;
+			return;
+		}
+		// Ensure omp- prefix after normalization
+		const finalName = normalized.startsWith("omp-") ? normalized : `omp-${normalized}`;
+		console.log(chalk.yellow(`Invalid plugin name. Normalized to: ${finalName}`));
+		pluginName = finalName;
+	}
 	const pluginDir = pluginName;
 
 	if (existsSync(pluginDir)) {
 		console.log(chalk.red(`Error: Directory ${pluginDir} already exists`));
+		process.exitCode = 1;
 		return;
 	}
 
@@ -149,5 +198,6 @@ Provide instructions for the agent here.
 		console.log(chalk.dim("  5. Publish: npm publish"));
 	} catch (err) {
 		console.log(chalk.red(`Error creating plugin: ${(err as Error).message}`));
+		process.exitCode = 1;
 	}
 }

package/src/commands/doctor.ts

@@ -1,12 +1,20 @@
 import { existsSync } from "node:fs";
+import { detectAllConflicts, formatConflicts } from "@omp/conflicts";
+import { getInstalledPlugins, loadPluginsJson, readPluginPackageJson, savePluginsJson } from "@omp/manifest";
+import {
+	GLOBAL_PACKAGE_JSON,
+	NODE_MODULES_DIR,
+	PLUGINS_DIR,
+	PROJECT_NODE_MODULES,
+	PROJECT_PLUGINS_JSON,
+	resolveScope,
+} from "@omp/paths";
+import { checkPluginSymlinks, createPluginSymlinks } from "@omp/symlinks";
 import chalk from "chalk";
-import { detectAllConflicts, formatConflicts } from "../conflicts.js";
-import { getInstalledPlugins, loadPluginsJson, readPluginPackageJson } from "../manifest.js";
-import { GLOBAL_PACKAGE_JSON, NODE_MODULES_DIR, PLUGINS_DIR } from "../paths.js";
-import { checkPluginSymlinks } from "../symlinks.js";
 
 export interface DoctorOptions {
 	global?: boolean;
+	local?: boolean;
 	fix?: boolean;
 	json?: boolean;
 }
@@ -22,7 +30,7 @@ interface DiagnosticResult {
  * Run health checks on the plugin system
  */
 export async function runDoctor(options: DoctorOptions = {}): Promise<void> {
-	const isGlobal = options.global !== false;
+	const isGlobal = resolveScope(options);
 	const results: DiagnosticResult[] = [];
 
 	console.log(chalk.blue("Running health checks...\n"));
@@ -45,7 +53,7 @@ export async function runDoctor(options: DoctorOptions = {}): Promise<void> {
 	}
 
 	// 2. Check package.json exists
-	const packageJsonPath = isGlobal ? GLOBAL_PACKAGE_JSON : ".pi/plugins.json";
+	const packageJsonPath = isGlobal ? GLOBAL_PACKAGE_JSON : PROJECT_PLUGINS_JSON;
 	if (!existsSync(packageJsonPath)) {
 		results.push({
 			check: "Package manifest",
@@ -62,7 +70,7 @@ export async function runDoctor(options: DoctorOptions = {}): Promise<void> {
 	}
 
 	// 3. Check node_modules exists
-	const nodeModules = isGlobal ? NODE_MODULES_DIR : ".pi/node_modules";
+	const nodeModules = isGlobal ? NODE_MODULES_DIR : PROJECT_NODE_MODULES;
 	if (!existsSync(nodeModules)) {
 		results.push({
 			check: "Node modules",
@@ -152,6 +160,38 @@ export async function runDoctor(options: DoctorOptions = {}): Promise<void> {
 		});
 	}
 
+	// 7. Check for missing omp dependencies
+	const missingDeps: string[] = [];
+	for (const [name, pkgJson] of installedPlugins) {
+		if (pkgJson.dependencies) {
+			for (const depName of Object.keys(pkgJson.dependencies)) {
+				const depPkgJson = await readPluginPackageJson(depName, isGlobal);
+				if (!depPkgJson) {
+					// Dependency not found in node_modules
+					// Check if it's supposed to be an omp plugin by looking in the plugins manifest
+					if (pluginsJson.plugins[depName]) {
+						missingDeps.push(`${name} requires ${depName} (not in node_modules)`);
+					}
+				} else if (depPkgJson.omp?.install && depPkgJson.omp.install.length > 0) {
+					// Dependency is an omp plugin (has install entries) and is present - that's fine
+					// But check if it's registered in the plugins manifest
+					if (!pluginsJson.plugins[depName]) {
+						missingDeps.push(`${name} requires omp plugin ${depName} (installed but not in manifest)`);
+					}
+				}
+			}
+		}
+	}
+
+	if (missingDeps.length > 0) {
+		results.push({
+			check: "Missing omp dependencies",
+			status: "warning",
+			message: missingDeps.join("; "),
+			fix: isGlobal ? "Run: npm install in ~/.pi/plugins" : "Run: npm install in .pi",
+		});
+	}
+
 	// Output results
 	if (options.json) {
 		console.log(JSON.stringify({ results }, null, 2));
@@ -194,6 +234,7 @@ export async function runDoctor(options: DoctorOptions = {}): Promise<void> {
 	} else {
 		if (errors.length > 0) {
 			console.log(chalk.red(`${errors.length} error(s) found`));
+			process.exitCode = 1;
 		}
 		if (warnings.length > 0) {
 			console.log(chalk.yellow(`${warnings.length} warning(s) found`));
@@ -214,4 +255,51 @@ export async function runDoctor(options: DoctorOptions = {}): Promise<void> {
 			console.log(chalk.dim(`  - ${s}`));
 		}
 	}
+
+	// Apply fixes if --fix flag was passed
+	if (options.fix) {
+		let fixedAnything = false;
+
+		// Fix broken/missing symlinks by re-creating them
+		if (brokenSymlinks.length > 0 || missingSymlinks.length > 0) {
+			console.log(chalk.blue("\nAttempting to fix broken/missing symlinks..."));
+			for (const [name, pkgJson] of installedPlugins) {
+				const symlinkResult = await createPluginSymlinks(name, pkgJson, isGlobal, false);
+				if (symlinkResult.created.length > 0) {
+					fixedAnything = true;
+					console.log(chalk.green(`  ✓ Re-created symlinks for ${name}`));
+				}
+				if (symlinkResult.errors.length > 0) {
+					for (const err of symlinkResult.errors) {
+						console.log(chalk.red(`  ✗ ${name}: ${err}`));
+					}
+				}
+			}
+		}
+
+		// Remove orphaned manifest entries
+		if (orphaned.length > 0) {
+			console.log(chalk.blue("\nRemoving orphaned entries from manifest..."));
+			for (const name of orphaned) {
+				delete pluginsJson.plugins[name];
+				console.log(chalk.green(`  ✓ Removed ${name}`));
+			}
+			await savePluginsJson(pluginsJson, isGlobal);
+			fixedAnything = true;
+		}
+
+		// Conflicts cannot be auto-fixed
+		if (conflicts.length > 0) {
+			console.log(chalk.yellow("\nConflicts cannot be auto-fixed. Please resolve manually:"));
+			for (const conflict of formatConflicts(conflicts)) {
+				console.log(chalk.dim(`  - ${conflict}`));
+			}
+		}
+
+		if (fixedAnything) {
+			console.log(chalk.green("\n✓ Fixes applied. Run 'omp doctor' again to verify."));
+		} else if (conflicts.length === 0) {
+			console.log(chalk.dim("\nNo fixable issues found."));
+		}
+	}
 }

package/src/commands/enable.ts

@@ -1,9 +1,11 @@
+import { loadPluginsJson, readPluginPackageJson, savePluginsJson } from "@omp/manifest";
+import { resolveScope } from "@omp/paths";
+import { checkPluginSymlinks, createPluginSymlinks, removePluginSymlinks } from "@omp/symlinks";
 import chalk from "chalk";
-import { loadPluginsJson, readPluginPackageJson, savePluginsJson } from "../manifest.js";
-import { createPluginSymlinks, removePluginSymlinks } from "../symlinks.js";
 
 export interface EnableDisableOptions {
 	global?: boolean;
+	local?: boolean;
 	json?: boolean;
 }
 
@@ -11,19 +13,21 @@ export interface EnableDisableOptions {
  * Enable a disabled plugin (re-create symlinks)
  */
 export async function enablePlugin(name: string, options: EnableDisableOptions = {}): Promise<void> {
-	const isGlobal = options.global !== false;
+	const isGlobal = resolveScope(options);
 
 	const pluginsJson = await loadPluginsJson(isGlobal);
 
 	// Check if plugin exists
 	if (!pluginsJson.plugins[name]) {
 		console.log(chalk.yellow(`Plugin "${name}" is not installed.`));
+		process.exitCode = 1;
 		return;
 	}
 
 	// Check if already enabled
 	if (!pluginsJson.disabled?.includes(name)) {
 		console.log(chalk.yellow(`Plugin "${name}" is already enabled.`));
+		process.exitCode = 1;
 		return;
 	}
 
@@ -32,12 +36,20 @@ export async function enablePlugin(name: string, options: EnableDisableOptions =
 		const pkgJson = await readPluginPackageJson(name, isGlobal);
 		if (!pkgJson) {
 			console.log(chalk.red(`Could not read package.json for ${name}`));
+			process.exitCode = 1;
 			return;
 		}
 
-		// Re-create symlinks
-		console.log(chalk.blue(`Enabling ${name}...`));
-		await createPluginSymlinks(name, pkgJson, isGlobal);
+		// Check if symlinks are already in place
+		const symlinkStatus = await checkPluginSymlinks(name, pkgJson, isGlobal);
+
+		if (symlinkStatus.valid.length > 0 && symlinkStatus.broken.length === 0 && symlinkStatus.missing.length === 0) {
+			console.log(chalk.yellow(`Plugin "${name}" symlinks are already in place.`));
+		} else {
+			// Re-create symlinks
+			console.log(chalk.blue(`Enabling ${name}...`));
+			await createPluginSymlinks(name, pkgJson, isGlobal);
+		}
 
 		// Remove from disabled list
 		pluginsJson.disabled = pluginsJson.disabled.filter((n) => n !== name);
@@ -50,6 +62,7 @@ export async function enablePlugin(name: string, options: EnableDisableOptions =
 		}
 	} catch (err) {
 		console.log(chalk.red(`Error enabling plugin: ${(err as Error).message}`));
+		process.exitCode = 1;
 	}
 }
 
@@ -57,19 +70,21 @@ export async function enablePlugin(name: string, options: EnableDisableOptions =
  * Disable a plugin (remove symlinks but keep installed)
  */
 export async function disablePlugin(name: string, options: EnableDisableOptions = {}): Promise<void> {
-	const isGlobal = options.global !== false;
+	const isGlobal = resolveScope(options);
 
 	const pluginsJson = await loadPluginsJson(isGlobal);
 
 	// Check if plugin exists
 	if (!pluginsJson.plugins[name]) {
 		console.log(chalk.yellow(`Plugin "${name}" is not installed.`));
+		process.exitCode = 1;
 		return;
 	}
 
 	// Check if already disabled
 	if (pluginsJson.disabled?.includes(name)) {
 		console.log(chalk.yellow(`Plugin "${name}" is already disabled.`));
+		process.exitCode = 1;
 		return;
 	}
 
@@ -78,12 +93,13 @@ export async function disablePlugin(name: string, options: EnableDisableOptions
 		const pkgJson = await readPluginPackageJson(name, isGlobal);
 		if (!pkgJson) {
 			console.log(chalk.red(`Could not read package.json for ${name}`));
+			process.exitCode = 1;
 			return;
 		}
 
 		// Remove symlinks
 		console.log(chalk.blue(`Disabling ${name}...`));
-		await removePluginSymlinks(name, pkgJson);
+		await removePluginSymlinks(name, pkgJson, isGlobal);
 
 		// Add to disabled list
 		if (!pluginsJson.disabled) {
@@ -101,5 +117,6 @@ export async function disablePlugin(name: string, options: EnableDisableOptions
 		}
 	} catch (err) {
 		console.log(chalk.red(`Error disabling plugin: ${(err as Error).message}`));
+		process.exitCode = 1;
 	}
 }

package/src/commands/info.ts

@@ -1,9 +1,10 @@
+import { npmInfo } from "@omp/npm";
 import chalk from "chalk";
-import { npmInfo } from "../npm.js";
 
 export interface InfoOptions {
 	json?: boolean;
 	versions?: boolean;
+	allVersions?: boolean;
 }
 
 /**
@@ -17,6 +18,7 @@ export async function showInfo(packageName: string, options: InfoOptions = {}):
 
 		if (!info) {
 			console.log(chalk.red(`Package not found: ${packageName}`));
+			process.exitCode = 1;
 			return;
 		}
 
@@ -59,6 +61,14 @@ export async function showInfo(packageName: string, options: InfoOptions = {}):
 			console.log(chalk.dim("keywords: ") + info.keywords.join(", "));
 		}
 
+		// Dependencies
+		if (info.dependencies && Object.keys(info.dependencies).length > 0) {
+			console.log(chalk.dim("\ndependencies:"));
+			for (const [depName, depVersion] of Object.entries(info.dependencies)) {
+				console.log(chalk.dim(`  ${depName}: ${depVersion}`));
+			}
+		}
+
 		// Is it an omp plugin?
 		const isOmpPlugin = info.keywords?.includes("omp-plugin");
 		if (isOmpPlugin) {
@@ -68,11 +78,36 @@ export async function showInfo(packageName: string, options: InfoOptions = {}):
 			console.log(chalk.dim("  It may work, but might not have omp.install configuration"));
 		}
 
+		// Show what files will be installed
+		if (info.omp?.install?.length) {
+			console.log(chalk.dim("\nFiles to install:"));
+			for (const entry of info.omp.install) {
+				console.log(chalk.dim(`  ${entry.src} → ${entry.dest}`));
+			}
+		}
+
 		// Versions
-		if (options.versions && info["dist-tags"]) {
-			console.log(chalk.dim("\ndist-tags:"));
-			for (const [tag, version] of Object.entries(info["dist-tags"])) {
-				console.log(chalk.dim(`  ${tag}: `) + version);
+		if (options.versions || options.allVersions) {
+			if (info["dist-tags"]) {
+				console.log(chalk.dim("\ndist-tags:"));
+				for (const [tag, version] of Object.entries(info["dist-tags"])) {
+					console.log(chalk.dim(`  ${tag}: `) + version);
+				}
+			}
+
+			if (info.versions?.length) {
+				console.log(chalk.dim("\nall versions:"));
+				if (options.allVersions) {
+					// Show all versions
+					console.log(chalk.dim(`  ${info.versions.join(", ")}`));
+				} else {
+					// Show last 10
+					const versionsToShow = info.versions.slice(-10);
+					console.log(chalk.dim(`  ${versionsToShow.join(", ")}`));
+					if (info.versions.length > 10) {
+						console.log(chalk.dim(`  ... and ${info.versions.length - 10} more (use --all-versions to see all)`));
+					}
+				}
 			}
 		}
 
@@ -80,5 +115,6 @@ export async function showInfo(packageName: string, options: InfoOptions = {}):
 		console.log(chalk.dim(`Install with: omp install ${packageName}`));
 	} catch (err) {
 		console.log(chalk.red(`Error fetching info: ${(err as Error).message}`));
+		process.exitCode = 1;
 	}
 }

package/src/commands/init.ts

@@ -1,7 +1,17 @@
 import { existsSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
+import { PROJECT_PI_DIR, PROJECT_PLUGINS_JSON } from "@omp/paths";
 import chalk from "chalk";
-import { PROJECT_PI_DIR, PROJECT_PLUGINS_JSON } from "../paths.js";
+
+/**
+ * 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;
+}
 
 export interface InitOptions {
 	force?: boolean;
@@ -15,6 +25,7 @@ export async function initProject(options: InitOptions = {}): Promise<void> {
 	if (existsSync(PROJECT_PLUGINS_JSON) && !options.force) {
 		console.log(chalk.yellow(`${PROJECT_PLUGINS_JSON} already exists.`));
 		console.log(chalk.dim("Use --force to overwrite"));
+		process.exitCode = 1;
 		return;
 	}
 
@@ -37,6 +48,13 @@ export async function initProject(options: InitOptions = {}): Promise<void> {
 		console.log(chalk.dim("  2. Or edit plugins.json directly"));
 		console.log(chalk.dim("  3. Run: omp install (to install all)"));
 	} catch (err) {
-		console.log(chalk.red(`Error initializing project: ${(err as Error).message}`));
+		const error = err as NodeJS.ErrnoException;
+		if (error.code === "EACCES" || error.code === "EPERM") {
+			console.log(chalk.red(formatPermissionError(error, PROJECT_PI_DIR)));
+			console.log(chalk.dim("  Check directory permissions or run with appropriate privileges."));
+		} else {
+			console.log(chalk.red(`Error initializing project: ${error.message}`));
+		}
+		process.exitCode = 1;
 	}
 }