@oh-my-pi/cli 0.1.0 → 0.2.0

package/src/symlinks.ts

@@ -1,24 +1,63 @@
 import { existsSync, lstatSync } from "node:fs";
 import { mkdir, readlink, rm, symlink } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { platform } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import type { OmpInstallEntry, PluginPackageJson } from "@omp/manifest";
+import { getPluginSourceDir } from "@omp/manifest";
+import { PI_CONFIG_DIR, PROJECT_PI_DIR } from "@omp/paths";
 import chalk from "chalk";
-import type { OmpInstallEntry, PluginPackageJson } from "./manifest.js";
-import { getPluginSourceDir } from "./manifest.js";
-import { PI_CONFIG_DIR } from "./paths.js";
+
+const isWindows = platform() === "win32";
+
+/**
+ * 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;
+}
+
+/**
+ * Validates that a target path stays within the base directory.
+ * Prevents path traversal attacks via malicious dest entries like '../../../etc/passwd'.
+ */
+function isPathWithinBase(basePath: string, targetPath: string): boolean {
+	const normalizedBase = resolve(basePath);
+	const resolvedTarget = resolve(basePath, targetPath);
+	// Must start with base path followed by separator (or be exactly the base)
+	return resolvedTarget === normalizedBase || resolvedTarget.startsWith(`${normalizedBase}/`);
+}
+
+/**
+ * Get the base directory for symlink destinations based on scope
+ */
+function getBaseDir(global: boolean): string {
+	return global ? PI_CONFIG_DIR : PROJECT_PI_DIR;
+}
 
 export interface SymlinkResult {
 	created: string[];
 	errors: string[];
 }
 
+export interface SymlinkRemovalResult {
+	removed: string[];
+	errors: string[];
+	skippedNonSymlinks: string[]; // Files that exist but aren't symlinks
+}
+
 /**
  * Create symlinks for a plugin's omp.install entries
+ * @param skipDestinations - Set of destination paths to skip (e.g., due to conflict resolution)
  */
 export async function createPluginSymlinks(
 	pluginName: string,
 	pkgJson: PluginPackageJson,
 	global = true,
 	verbose = true,
+	skipDestinations?: Set<string>,
 ): Promise<SymlinkResult> {
 	const result: SymlinkResult = { created: [], errors: [] };
 	const sourceDir = getPluginSourceDir(pluginName, global);
@@ -30,10 +69,30 @@ export async function createPluginSymlinks(
 		return result;
 	}
 
+	const baseDir = getBaseDir(global);
+
 	for (const entry of pkgJson.omp.install) {
+		// Skip destinations that the user chose to keep from existing plugins
+		if (skipDestinations?.has(entry.dest)) {
+			if (verbose) {
+				console.log(chalk.dim(`  Skipped: ${entry.dest} (conflict resolved to existing plugin)`));
+			}
+			continue;
+		}
+
+		// Validate dest path stays within base directory (prevents path traversal attacks)
+		if (!isPathWithinBase(baseDir, entry.dest)) {
+			const msg = `Path traversal blocked: ${entry.dest} escapes base directory`;
+			result.errors.push(msg);
+			if (verbose) {
+				console.log(chalk.red(`  ✗ ${msg}`));
+			}
+			continue;
+		}
+
 		try {
 			const src = join(sourceDir, entry.src);
-			const dest = join(PI_CONFIG_DIR, entry.dest);
+			const dest = join(baseDir, entry.dest);
 
 			// Check if source exists
 			if (!existsSync(src)) {
@@ -52,18 +111,41 @@ export async function createPluginSymlinks(
 				await rm(dest, { force: true, recursive: true });
 			} catch {}
 
-			// Create symlink
-			await symlink(src, dest);
+			// Create symlink (use junctions on Windows for directories to avoid admin requirement)
+			try {
+				if (isWindows) {
+					const stats = lstatSync(src);
+					if (stats.isDirectory()) {
+						await symlink(src, dest, "junction");
+					} else {
+						await symlink(src, dest, "file");
+					}
+				} else {
+					await symlink(src, dest);
+				}
+			} catch (symlinkErr) {
+				const error = symlinkErr as NodeJS.ErrnoException;
+				if (isWindows && error.code === "EPERM") {
+					console.log(chalk.red(`  Permission denied creating symlink.`));
+					console.log(chalk.dim("  On Windows, enable Developer Mode or run as Administrator."));
+					console.log(chalk.dim("  Settings > Update & Security > For developers > Developer Mode"));
+				}
+				throw symlinkErr;
+			}
 			result.created.push(entry.dest);
 
 			if (verbose) {
 				console.log(chalk.dim(`  Linked: ${entry.dest} → ${entry.src}`));
 			}
 		} catch (err) {
-			const msg = `Failed to link ${entry.dest}: ${(err as Error).message}`;
+			const error = err as NodeJS.ErrnoException;
+			const msg = `Failed to link ${entry.dest}: ${formatPermissionError(error, join(baseDir, entry.dest))}`;
 			result.errors.push(msg);
 			if (verbose) {
 				console.log(chalk.red(`  ✗ ${msg}`));
+				if (error.code === "EACCES" || error.code === "EPERM") {
+					console.log(chalk.dim("  Check directory permissions or run with appropriate privileges."));
+				}
 			}
 		}
 	}
@@ -77,30 +159,56 @@ export async function createPluginSymlinks(
 export async function removePluginSymlinks(
 	_pluginName: string,
 	pkgJson: PluginPackageJson,
+	global = true,
 	verbose = true,
-): Promise<SymlinkResult> {
-	const result: SymlinkResult = { created: [], errors: [] };
+): Promise<SymlinkRemovalResult> {
+	const result: SymlinkRemovalResult = { removed: [], errors: [], skippedNonSymlinks: [] };
 
 	if (!pkgJson.omp?.install?.length) {
 		return result;
 	}
 
+	const baseDir = getBaseDir(global);
+
 	for (const entry of pkgJson.omp.install) {
-		const dest = join(PI_CONFIG_DIR, entry.dest);
+		// Validate dest path stays within base directory (prevents path traversal attacks)
+		if (!isPathWithinBase(baseDir, entry.dest)) {
+			const msg = `Path traversal blocked: ${entry.dest} escapes base directory`;
+			result.errors.push(msg);
+			if (verbose) {
+				console.log(chalk.red(`  ✗ ${msg}`));
+			}
+			continue;
+		}
+
+		const dest = join(baseDir, entry.dest);
 
 		try {
 			if (existsSync(dest)) {
+				const stats = lstatSync(dest);
+				if (!stats.isSymbolicLink()) {
+					result.skippedNonSymlinks.push(dest);
+					if (verbose) {
+						console.log(chalk.yellow(`  ⚠ Skipping ${entry.dest}: not a symlink (may contain user data)`));
+					}
+					continue;
+				}
+
 				await rm(dest, { force: true, recursive: true });
-				result.created.push(entry.dest);
+				result.removed.push(entry.dest);
 				if (verbose) {
 					console.log(chalk.dim(`  Removed: ${entry.dest}`));
 				}
 			}
 		} catch (err) {
-			const msg = `Failed to remove ${entry.dest}: ${(err as Error).message}`;
+			const error = err as NodeJS.ErrnoException;
+			const msg = `Failed to remove ${entry.dest}: ${formatPermissionError(error, dest)}`;
 			result.errors.push(msg);
 			if (verbose) {
 				console.log(chalk.yellow(`  ⚠ ${msg}`));
+				if (error.code === "EACCES" || error.code === "EPERM") {
+					console.log(chalk.dim("  Check directory permissions or run with appropriate privileges."));
+				}
 			}
 		}
 	}
@@ -118,14 +226,21 @@ export async function checkPluginSymlinks(
 ): Promise<{ valid: string[]; broken: string[]; missing: string[] }> {
 	const result = { valid: [] as string[], broken: [] as string[], missing: [] as string[] };
 	const sourceDir = getPluginSourceDir(pluginName, global);
+	const baseDir = getBaseDir(global);
 
 	if (!pkgJson.omp?.install?.length) {
 		return result;
 	}
 
 	for (const entry of pkgJson.omp.install) {
+		// Skip entries with path traversal (treat as broken)
+		if (!isPathWithinBase(baseDir, entry.dest)) {
+			result.broken.push(entry.dest);
+			continue;
+		}
+
 		const src = join(sourceDir, entry.src);
-		const dest = join(PI_CONFIG_DIR, entry.dest);
+		const dest = join(baseDir, entry.dest);
 
 		if (!existsSync(dest)) {
 			result.missing.push(entry.dest);
@@ -178,11 +293,13 @@ export async function getPluginForSymlink(
 export async function traceInstalledFile(
 	filePath: string,
 	installedPlugins: Map<string, PluginPackageJson>,
+	global = true,
 ): Promise<{ plugin: string; entry: OmpInstallEntry } | null> {
-	// Normalize the path relative to PI_CONFIG_DIR
+	// Normalize the path relative to the base directory
+	const baseDir = getBaseDir(global);
 	let relativePath = filePath;
-	if (filePath.startsWith(PI_CONFIG_DIR)) {
-		relativePath = filePath.slice(PI_CONFIG_DIR.length + 1);
+	if (filePath.startsWith(baseDir)) {
+		relativePath = filePath.slice(baseDir.length + 1);
 	}
 
 	for (const [name, pkgJson] of installedPlugins) {

package/tsconfig.json

@@ -1,7 +1,7 @@
 {
 	"compilerOptions": {
 		"target": "ES2022",
-		"module": "Node16",
+		"module": "ESNext",
 		"lib": ["ES2022"],
 		"strict": true,
 		"esModuleInterop": true,
@@ -12,12 +12,16 @@
 		"sourceMap": true,
 		"inlineSources": true,
 		"inlineSourceMap": false,
-		"moduleResolution": "Node16",
+		"moduleResolution": "bundler",
 		"resolveJsonModule": true,
 		"allowImportingTsExtensions": false,
 		"outDir": "./dist",
 		"rootDir": "./src",
-		"types": ["node", "bun-types"]
+		"types": ["node", "bun-types"],
+		"baseUrl": ".",
+		"paths": {
+			"@omp/*": ["src/*"]
+		}
 	},
 	"include": ["src/**/*"],
 	"exclude": ["node_modules", "dist"]

package/CHECK.md

@@ -1,352 +0,0 @@
-# Implementation Review Checklist
-
-Review the oh-my-pi implementation against these requirements. For each item, verify it works correctly and check the listed edge cases.
-
----
-
-## 1. Install Command (`omp install`)
-
-### Core functionality
-- [ ] `omp install pkg-name` installs from npm
-- [ ] `omp install pkg@version` respects version specifier
-- [ ] `omp install @scope/pkg` handles scoped packages
-- [ ] `omp install ./path` copies local directory
-- [ ] `omp install ~/path` expands home directory
-- [ ] `omp install` (no args) installs from plugins.json
-- [ ] Creates symlinks for each `omp.install` entry
-
-### Edge cases
-- [ ] Package not found on npm → clear error message
-- [ ] Invalid version specifier → graceful failure
-- [ ] Local path doesn't exist → error before any changes
-- [ ] `omp.install` has missing source file → skip with warning, continue others
-- [ ] Circular dependencies between plugins → handled without infinite loop
-- [ ] Nested dependencies with omp field → all get symlinked
-- [ ] Package has no `omp` field → installs but no symlinks (warning?)
-- [ ] Network failure mid-install → rollback partial install
-- [ ] Disk full → appropriate error
-- [ ] Symlink target directory doesn't exist → creates parent dirs
-- [ ] `omp install` with empty plugins.json → helpful message
-
-### Flags
-- [ ] `--global` installs to ~/.pi/plugins/
-- [ ] `--save` adds to plugins.json
-- [ ] `--save-dev` adds to devDependencies
-- [ ] `--force` overwrites conflicts without prompting
-- [ ] `--json` outputs JSON format
-
----
-
-## 2. Conflict Detection
-
-### Core functionality
-- [ ] Detects when two plugins install to same destination
-- [ ] Interactive prompt offers choices: plugin1, plugin2, abort
-- [ ] User can select which plugin wins
-- [ ] Abort rolls back the install
-
-### Edge cases
-- [ ] Three+ plugins with same destination → all listed
-- [ ] Conflict with already-installed plugin → prompt before npm install
-- [ ] Conflict within same plugin's install array (duplicate dest) → error
-- [ ] `--force` skips all prompts → overwrites
-- [ ] Non-interactive terminal (CI) → fail or use --force
-
----
-
-## 3. Uninstall Command (`omp uninstall`)
-
-### Core functionality
-- [ ] `omp uninstall pkg` removes package
-- [ ] Removes all symlinks from `omp.install`
-- [ ] Removes from package.json/plugins.json
-
-### Edge cases
-- [ ] Plugin not installed → clear error
-- [ ] Symlink already deleted manually → graceful (ENOENT ignored)
-- [ ] Symlink replaced by real file → remove anyway or warn?
-- [ ] Plugin has dependencies that other plugins also use → don't break them
-- [ ] Partial uninstall (some symlinks fail) → report what failed
-
----
-
-## 4. Update Command (`omp update`)
-
-### Core functionality
-- [ ] `omp update` updates all plugins
-- [ ] `omp update pkg` updates specific plugin
-- [ ] Respects semver ranges from plugins.json
-- [ ] Re-creates symlinks after update
-
-### Edge cases
-- [ ] Package already at latest → no-op with message
-- [ ] Major version available but range is `^` → doesn't update
-- [ ] Package removed from npm → error handling
-- [ ] Update changes `omp.install` entries → old symlinks removed, new created
-- [ ] Linked (dev) plugins → skipped with message
-
----
-
-## 5. List Command (`omp list`)
-
-### Core functionality
-- [ ] Shows all installed plugins
-- [ ] Shows version for each
-- [ ] Shows (linked) badge for dev plugins
-
-### Edge cases
-- [ ] No plugins installed → helpful message
-- [ ] Plugin in plugins.json but not in node_modules → show as broken
-- [ ] Corrupt package.json → graceful error
-- [ ] `--json` output is valid JSON
-
----
-
-## 6. Link Command (`omp link`)
-
-### Core functionality
-- [ ] `omp link ./path` creates symlink to source directory
-- [ ] Marks as linked in manifest
-- [ ] Creates symlinks from `omp.install`
-
-### Edge cases
-- [ ] Path doesn't exist → error
-- [ ] Path has no package.json → uses directory name, creates minimal
-- [ ] Path has omp.json (legacy) → converts to package.json format
-- [ ] Already linked → re-link or error?
-- [ ] `-n, --name` overrides plugin name
-- [ ] Linked plugin updated externally → symlinks still work
-
----
-
-## 7. Init Command (`omp init`)
-
-### Core functionality
-- [ ] Creates `.pi/plugins.json` in current directory
-- [ ] Correct initial structure: `{ "plugins": {}, "disabled": [] }`
-
-### Edge cases
-- [ ] File already exists → error unless `--force`
-- [ ] `.pi/` directory doesn't exist → creates it
-- [ ] No write permission → clear error
-
----
-
-## 8. Search Command (`omp search`)
-
-### Core functionality
-- [ ] `omp search query` searches npm for `keywords:omp-plugin`
-- [ ] Shows name, version, description
-
-### Edge cases
-- [ ] No results → helpful message
-- [ ] npm registry unavailable → timeout with error
-- [ ] Very long description → truncated
-- [ ] `--limit` respected
-- [ ] Special characters in query → properly escaped
-
----
-
-## 9. Info Command (`omp info`)
-
-### Core functionality
-- [ ] `omp info pkg` shows package details
-- [ ] Shows: name, version, description, dependencies, omp.install entries
-
-### Edge cases
-- [ ] Package not found → clear error
-- [ ] Package exists but no omp field → show warning
-- [ ] `--versions` shows available versions
-- [ ] `--json` valid JSON output
-
----
-
-## 10. Outdated Command (`omp outdated`)
-
-### Core functionality
-- [ ] Lists plugins with newer versions available
-- [ ] Shows current, wanted, latest columns
-
-### Edge cases
-- [ ] All up to date → "All plugins up to date"
-- [ ] npm outdated returns exit code 1 → still parses output
-- [ ] Plugin not on npm anymore → shown as error row
-- [ ] Linked plugins → excluded from check
-
----
-
-## 11. Doctor Command (`omp doctor`)
-
-### Core functionality
-- [ ] Checks for broken symlinks
-- [ ] Checks for conflicts
-- [ ] Reports missing dependencies
-
-### Edge cases
-- [ ] No issues → "All good"
-- [ ] Symlink target deleted → reported as broken
-- [ ] Symlink replaced by real file → reported
-- [ ] `--fix` repairs broken symlinks
-- [ ] `--fix` can't fix conflict → reports
-
----
-
-## 12. Create Command (`omp create`)
-
-### Core functionality
-- [ ] `omp create my-plugin` scaffolds new plugin
-- [ ] Creates package.json with omp field
-- [ ] Creates directory structure
-
-### Edge cases
-- [ ] Directory already exists → error
-- [ ] Invalid plugin name (spaces, special chars) → normalized or error
-- [ ] `--description` sets description
-- [ ] `--author` sets author
-
----
-
-## 13. Why Command (`omp why`)
-
-### Core functionality
-- [ ] `omp why agent/themes/dark.json` shows which plugin installed it
-- [ ] Shows plugin name and source path
-
-### Edge cases
-- [ ] File not installed by any plugin → "Not installed by omp"
-- [ ] File is manually created (not symlink) → detect and report
-- [ ] Relative vs absolute path → both work
-- [ ] File doesn't exist → appropriate error
-
----
-
-## 14. Enable/Disable Commands
-
-### Core functionality
-- [ ] `omp disable pkg` removes symlinks, keeps in node_modules
-- [ ] `omp enable pkg` restores symlinks
-- [ ] Disabled list persisted
-
-### Edge cases
-- [ ] Disable already-disabled → no-op or error
-- [ ] Enable not-disabled → no-op
-- [ ] Enable not-installed → error
-- [ ] Symlinks manually restored → enable detects and handles
-
----
-
-## 15. Project-Local vs Global
-
-### Core functionality
-- [ ] Default is global (~/.pi/)
-- [ ] With `.pi/plugins.json` in cwd, uses project-local
-- [ ] `--global` forces global even with local config
-- [ ] Symlinks go to correct location per scope
-
-### Edge cases
-- [ ] Nested projects (parent and child have .pi/) → uses closest
-- [ ] Project-local install then run from parent dir → correct behavior
-- [ ] Same plugin installed globally and locally → local takes precedence?
-
----
-
-## 16. Migration (`omp migrate`)
-
-### Core functionality
-- [ ] Detects legacy manifest.json
-- [ ] Converts to package.json format
-- [ ] Preserves all plugin info
-- [ ] Re-creates symlinks
-
-### Edge cases
-- [ ] No legacy manifest → "Nothing to migrate"
-- [ ] Partial migration (some plugins fail) → reports
-- [ ] Legacy plugin source gone → reports but continues
-- [ ] Backup of manifest.json created
-
----
-
-## 17. Lock File
-
-### Core functionality
-- [ ] package-lock.json generated for global
-- [ ] plugins-lock.json generated for project-local
-- [ ] Reproducible installs with lock file
-
-### Edge cases
-- [ ] Lock file corrupt → regenerate with warning
-- [ ] Lock file deleted → works but warns about reproducibility
-
----
-
-## 18. Symlinks Module
-
-### Core functionality
-- [ ] Creates symlinks correctly
-- [ ] Removes symlinks on uninstall
-- [ ] Validates symlink health
-
-### Edge cases
-- [ ] **BUG CHECK: Project-local uses correct base path (.pi/ not ~/.pi/)**
-- [ ] Destination is a directory → symlink whole directory
-- [ ] Destination is a file → symlink file
-- [ ] Parent directories created recursively
-- [ ] Windows compatibility (if applicable) → use junctions or requires admin
-
----
-
-## 19. npm Module
-
-### Core functionality
-- [ ] npm install works with prefix
-- [ ] npm info fetches package data
-- [ ] npm search returns results
-- [ ] npm outdated parsed correctly
-
-### Edge cases
-- [ ] npm not installed → clear error
-- [ ] npm version too old → check and warn
-- [ ] Private registry → respects .npmrc
-- [ ] Scoped package with private registry → works
-
----
-
-## 20. General Edge Cases
-
-### Error handling
-- [ ] All commands have try/catch at top level
-- [ ] Errors include actionable messages
-- [ ] Stack traces hidden unless DEBUG
-
-### Permissions
-- [ ] No sudo required for ~/.pi
-- [ ] Handles permission denied gracefully
-- [ ] Doesn't follow symlinks outside allowed paths (security)
-
-### Concurrency
-- [ ] Two `omp install` at once → lock file prevents corruption
-- [ ] Interrupted install → recoverable state
-
-### Unicode/i18n
-- [ ] Plugin names with unicode → handled
-- [ ] Paths with spaces → quoted correctly
-- [ ] Paths with unicode → work on all platforms
-
----
-
-## Verification Steps
-
-For each section above:
-1. Read the relevant source file
-2. Trace the code path for the happy case
-3. Check each edge case is handled
-4. Note any missing error handling
-5. Run the command if possible to verify
-
-Report findings as:
-```
-## [Command Name]
-✓ Working: [list of working features]
-✗ Missing: [list of unimplemented features]
-⚠ Issues: [list of bugs or edge cases not handled]
-```