opencode-marketplace 0.1.0

package/README.md

@@ -0,0 +1,181 @@
+# OpenCode Marketplace
+
+CLI marketplace for OpenCode plugins - declarative, file-based plugin distribution for commands, agents, and skills.
+
+## Overview
+
+OpenCode Marketplace brings a convention-based plugin system to OpenCode. Instead of npm packages with programmatic hooks, plugins are simply directories with well-known folder structures that get auto-discovered and installed.
+
+**Key Features:**
+- 📦 Install plugins from local directories
+- 🎯 Zero-config, convention-based discovery
+- 🔄 Content-hash based change detection (no version numbers)
+- 🎭 Support for commands, agents, and skills
+- 🌍 User-global or project-local scope
+- 🧹 Clean install/uninstall workflows
+
+## Installation
+
+```bash
+bunx opencode-marketplace <command>
+```
+
+Or install globally:
+
+```bash
+bun install -g opencode-marketplace
+```
+
+## Quick Start
+
+### Install a Plugin
+
+```bash
+opencode-marketplace install /path/to/my-plugin
+```
+
+### List Installed Plugins
+
+```bash
+opencode-marketplace list
+```
+
+### Scan a Plugin (Dry Run)
+
+```bash
+opencode-marketplace scan /path/to/my-plugin
+```
+
+### Uninstall a Plugin
+
+```bash
+opencode-marketplace uninstall my-plugin
+```
+
+## Plugin Structure
+
+A plugin is a directory containing components in well-known locations:
+
+```
+my-plugin/
+├── command/           # or .opencode/command/, .claude/commands/
+│   └── reflect.md
+├── agent/            # or .opencode/agent/, .claude/agents/
+│   └── reviewer.md
+└── skill/            # or .opencode/skill/, .claude/skills/
+    └── code-review/
+        ├── SKILL.md
+        └── data.json
+```
+
+### Discovery Priority
+
+The tool searches for components in this order (first match wins):
+
+| Component | Priority 1 | Priority 2 | Priority 3 | Priority 4 |
+|-----------|------------|------------|------------|------------|
+| Commands | `.opencode/command/` | `.claude/commands/` | `./command/` | `./commands/` |
+| Agents | `.opencode/agent/` | `.claude/agents/` | `./agent/` | `./agents/` |
+| Skills | `.opencode/skill/` | `.claude/skills/` | `./skill/` | `./skills/` |
+
+## How It Works
+
+### 1. Discovery
+The tool scans your plugin directory for components using convention-based paths.
+
+### 2. Namespacing
+Files are copied with a prefix to avoid conflicts:
+- Source: `my-plugin/command/reflect.md`
+- Target: `~/.config/opencode/command/my-plugin--reflect.md`
+
+### 3. Registry
+Installed plugins are tracked in `~/.config/opencode/plugins/installed.json` with:
+- Content hash (instead of version)
+- Source path
+- Installed components
+- Scope (user/project)
+
+### 4. Change Detection
+Content hashing ensures you only reinstall when files actually change.
+
+## Scopes
+
+| Scope | Target Location | Registry |
+|-------|----------------|----------|
+| `user` (default) | `~/.config/opencode/` | `~/.config/opencode/plugins/installed.json` |
+| `project` | `.opencode/` | `.opencode/plugins/installed.json` |
+
+## Example
+
+```bash
+$ opencode-marketplace install ~/plugins/misc
+
+Installing misc [a1b2c3d4]...
+  → command/misc--reflect.md
+  → skill/misc--git-review/
+
+Installed misc (1 command, 1 skill) to user scope.
+```
+
+```bash
+$ opencode-marketplace list
+
+Installed plugins (user scope):
+  misc [a1b2c3d4] (1 command, 1 skill)
+    Source: /home/user/plugins/misc
+```
+
+## Development
+
+### Setup
+
+```bash
+bun install
+```
+
+### Run Locally
+
+```bash
+bun run dev
+```
+
+### Test
+
+```bash
+bun test
+```
+
+### Lint & Format
+
+```bash
+bun run lint
+bun run format
+```
+
+## Tech Stack
+
+- **Runtime**: Bun
+- **Language**: TypeScript
+- **CLI Framework**: CAC
+- **Testing**: Bun's built-in test runner
+
+## Roadmap
+
+**v1** (Current):
+- ✅ Local directory installation
+- ✅ Commands, agents, and skills support
+- ✅ User/project scope
+- ✅ Content-hash based updates
+
+**Future**:
+- Remote installation (GitHub URLs)
+- Plugin dependencies
+- Marketplace browsing
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Please open an issue or PR on [GitHub](https://github.com/NikiforovAll/opencode-marketplace).

package/bin/opencode

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { main } from "../src/index";
+
+main();

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "opencode-marketplace",
+  "version": "0.1.0",
+  "description": "CLI marketplace for OpenCode plugins",
+  "type": "module",
+  "author": "nikiforovall",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nikiforovall/opencode-marketplace.git"
+  },
+  "keywords": [
+    "opencode",
+    "mcp",
+    "marketplace",
+    "cli",
+    "plugins"
+  ],
+  "files": [
+    "bin",
+    "src"
+  ],
+  "bin": {
+    "opencode": "bin/opencode"
+  },
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "build": "bun build ./src/index.ts --compile --outfile opencode-marketplace",
+    "test": "bun test",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format .",
+    "format:fix": "biome format --write .",
+    "typecheck": "tsc --noEmit",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.10",
+    "@types/bun": "latest",
+    "husky": "^9.1.7",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "cac": "^6.7.14"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,68 @@
+import { cac } from "cac";
+import { version } from "../package.json";
+import { install } from "./commands/install";
+import { list } from "./commands/list";
+import { scan } from "./commands/scan";
+import { uninstall } from "./commands/uninstall";
+
+export function run(argv = process.argv) {
+  const cli = cac("opencode-marketplace");
+
+  cli
+    .command("install <path>", "Install a plugin from a local directory")
+    .option("--scope <scope>", "Installation scope (user/project)", { default: "user" })
+    .option("--force", "Overwrite existing components", { default: false })
+    .action((path, options) => {
+      if (options.scope !== "user" && options.scope !== "project") {
+        console.error(`Invalid scope: ${options.scope}. Must be 'user' or 'project'.`);
+        process.exit(1);
+      }
+      return install(path, options);
+    });
+
+  cli
+    .command("uninstall <name>", "Uninstall a plugin")
+    .option("--scope <scope>", "Installation scope (user/project)", { default: "user" })
+    .action((name, options) => {
+      if (options.scope !== "user" && options.scope !== "project") {
+        console.error(`Invalid scope: ${options.scope}. Must be 'user' or 'project'.`);
+        process.exit(1);
+      }
+      return uninstall(name, options);
+    });
+
+  cli
+    .command("list", "List installed plugins")
+    .option("--scope <scope>", "Filter by scope (user/project)")
+    .action((options) => {
+      if (options.scope && options.scope !== "user" && options.scope !== "project") {
+        console.error(`Invalid scope: ${options.scope}. Must be 'user' or 'project'.`);
+        process.exit(1);
+      }
+      return list(options);
+    });
+
+  cli
+    .command("scan <path>", "Scan a directory for plugin components (dry-run)")
+    .action((path, options) => {
+      return scan(path, options);
+    });
+
+  // Global options
+  cli.option("--verbose", "Enable verbose logging");
+
+  cli.help();
+  cli.version(version);
+
+  try {
+    cli.parse(argv);
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("missing required args")) {
+      console.error(error.message);
+      cli.outputHelp();
+    } else {
+      console.error(error instanceof Error ? error.message : String(error));
+    }
+    process.exit(1);
+  }
+}

package/src/commands/install.ts

@@ -0,0 +1,222 @@
+import { existsSync } from "node:fs";
+import { copyFile, cp, mkdir } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
+import { discoverComponents } from "../discovery";
+import { formatComponentCount } from "../format";
+import { computePluginHash, resolvePluginName } from "../identity";
+import { ensureComponentDirsExist, getComponentTargetPath } from "../paths";
+import { getInstalledPlugin, loadRegistry, saveRegistry } from "../registry";
+import type { ComponentType, DiscoveredComponent, InstalledPlugin, Scope } from "../types";
+
+export interface InstallOptions {
+  scope: "user" | "project";
+  force: boolean;
+  verbose?: boolean;
+}
+
+interface ConflictInfo {
+  component: DiscoveredComponent;
+  targetPath: string;
+  conflictingPlugin: string | null; // null = untracked file
+}
+
+export async function install(path: string, options: InstallOptions) {
+  const { scope, force, verbose } = options;
+
+  try {
+    // Step 1: Validate plugin directory exists
+    const pluginPath = resolve(path);
+    if (!existsSync(pluginPath)) {
+      throw new Error(`Plugin directory not found: ${path}`);
+    }
+
+    // Step 2: Resolve plugin identity
+    const pluginName = resolvePluginName(pluginPath);
+    if (verbose) {
+      console.log(`[VERBOSE] Resolved plugin name: ${pluginName}`);
+    }
+
+    // Step 3: Discover components
+    const components = await discoverComponents(pluginPath, pluginName);
+    if (components.length === 0) {
+      throw new Error(
+        `No components found in ${path}. Ensure plugin contains command/, agent/, or skill/ directories with valid components.`,
+      );
+    }
+
+    // Step 4: Compute plugin hash
+    const pluginHash = await computePluginHash(components);
+    const shortHash = pluginHash.substring(0, 8);
+
+    if (verbose) {
+      console.log(`[VERBOSE] Plugin hash: ${pluginHash}`);
+      console.log(`[VERBOSE] Found ${components.length} component(s)`);
+    }
+
+    console.log(`Installing ${pluginName} [${shortHash}]...`);
+
+    // Step 5: Check for existing installation
+    const existingPlugin = await getInstalledPlugin(pluginName, scope);
+
+    if (existingPlugin) {
+      if (existingPlugin.hash === pluginHash) {
+        // Same plugin, same hash - reinstall
+        if (verbose) {
+          console.log(`[VERBOSE] Reinstalling existing plugin (same hash)`);
+        }
+      } else {
+        // Same plugin, different hash - update
+        if (verbose) {
+          console.log(
+            `[VERBOSE] Updating plugin from [${existingPlugin.hash.substring(0, 8)}] to [${shortHash}]`,
+          );
+        }
+      }
+    }
+
+    // Step 6: Detect conflicts
+    const conflicts = await detectConflicts(components, pluginName, scope);
+
+    if (conflicts.length > 0 && !force) {
+      console.error("\nConflict detected:");
+      for (const conflict of conflicts) {
+        if (conflict.conflictingPlugin) {
+          console.error(
+            `  ${conflict.component.type}/${conflict.component.targetName} already installed by plugin "${conflict.conflictingPlugin}"`,
+          );
+        } else {
+          console.error(
+            `  ${conflict.component.type}/${conflict.component.targetName} exists but is untracked`,
+          );
+        }
+      }
+      console.error("\nUse --force to override existing files.");
+      throw new Error("Installation aborted due to conflicts");
+    }
+
+    if (conflicts.length > 0 && force && verbose) {
+      console.log(`[VERBOSE] Overriding ${conflicts.length} conflicting file(s) with --force`);
+    }
+
+    // Step 7: Ensure target directories exist
+    await ensureComponentDirsExist(scope);
+
+    // Step 8: Copy components
+    const installedComponents = {
+      commands: [] as string[],
+      agents: [] as string[],
+      skills: [] as string[],
+    };
+
+    // Sort components by name to ensure deterministic installation order and registry entry
+    const sortedComponents = [...components].sort((a, b) => a.name.localeCompare(b.name));
+
+    for (const component of sortedComponents) {
+      const targetPath = getComponentTargetPath(pluginName, component.name, component.type, scope);
+
+      // Remove trailing slash for copying
+      const normalizedTarget = targetPath.endsWith("/") ? targetPath.slice(0, -1) : targetPath;
+
+      if (component.type === "skill") {
+        // Recursive directory copy
+        await mkdir(dirname(normalizedTarget), { recursive: true });
+        await cp(component.sourcePath, normalizedTarget, { recursive: true });
+        installedComponents.skills.push(basename(normalizedTarget));
+      } else if (component.type === "command") {
+        // Single file copy for commands
+        await mkdir(dirname(normalizedTarget), { recursive: true });
+        await copyFile(component.sourcePath, normalizedTarget);
+        installedComponents.commands.push(basename(normalizedTarget));
+      } else {
+        // Single file copy for agents
+        await mkdir(dirname(normalizedTarget), { recursive: true });
+        await copyFile(component.sourcePath, normalizedTarget);
+        installedComponents.agents.push(basename(normalizedTarget));
+      }
+
+      console.log(`  → ${component.type}/${component.targetName}`);
+    }
+
+    // Step 9: Update registry
+    const registry = await loadRegistry(scope);
+
+    const newPlugin: InstalledPlugin = {
+      name: pluginName,
+      hash: pluginHash,
+      scope,
+      sourcePath: pluginPath,
+      installedAt: new Date().toISOString(),
+      components: installedComponents,
+    };
+
+    registry.plugins[pluginName] = newPlugin;
+    await saveRegistry(registry, scope);
+
+    // Step 10: Print success message
+    const componentCounts = formatComponentCount(installedComponents);
+    console.log(`\nInstalled ${pluginName} (${componentCounts}) to ${scope} scope.`);
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(`\nError: ${error.message}`);
+    } else {
+      console.error("\nUnknown error occurred during installation");
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * Detects conflicts for components that would overwrite files from other plugins.
+ * Returns conflicts where:
+ * - File exists and belongs to a different plugin
+ * - File exists but is untracked (not in registry)
+ */
+async function detectConflicts(
+  components: DiscoveredComponent[],
+  pluginName: string,
+  scope: Scope,
+): Promise<ConflictInfo[]> {
+  const conflicts: ConflictInfo[] = [];
+  const registry = await loadRegistry(scope);
+
+  for (const component of components) {
+    const targetPath = getComponentTargetPath(pluginName, component.name, component.type, scope);
+
+    // Remove trailing slash for existence check
+    const normalizedTarget = targetPath.endsWith("/") ? targetPath.slice(0, -1) : targetPath;
+
+    if (existsSync(normalizedTarget)) {
+      // Find which plugin owns this component
+      const owningPlugin = findOwningPlugin(registry, component.type, component.targetName);
+
+      // Conflict if owned by different plugin OR untracked
+      if (owningPlugin !== pluginName) {
+        conflicts.push({
+          component,
+          targetPath: normalizedTarget,
+          conflictingPlugin: owningPlugin,
+        });
+      }
+    }
+  }
+
+  return conflicts;
+}
+
+/**
+ * Finds which plugin owns a specific component by searching the registry.
+ * Returns null if the component is not tracked.
+ */
+function findOwningPlugin(
+  registry: { plugins: Record<string, InstalledPlugin> },
+  componentType: ComponentType,
+  targetName: string,
+): string | null {
+  for (const [pluginName, plugin] of Object.entries(registry.plugins)) {
+    const componentList = plugin.components[`${componentType}s` as keyof typeof plugin.components];
+    if (componentList.includes(targetName)) {
+      return pluginName;
+    }
+  }
+  return null;
+}

package/src/commands/list.ts

@@ -0,0 +1,76 @@
+import { formatComponentCount } from "../format";
+import { getAllInstalledPlugins } from "../registry";
+import type { InstalledPlugin, Scope } from "../types";
+
+export interface ListOptions {
+  scope?: Scope;
+  verbose?: boolean;
+}
+
+export async function list(options: ListOptions) {
+  if (options.verbose) {
+    console.log("[VERBOSE] Listing plugins with options:", options);
+  }
+
+  const plugins = await getAllInstalledPlugins(options.scope);
+
+  // Filter by scope if specified
+  const filteredPlugins = options.scope
+    ? plugins.filter((plugin) => plugin.scope === options.scope)
+    : plugins;
+
+  if (filteredPlugins.length === 0) {
+    const scopeText = options.scope ? `${options.scope} scope` : "any scope";
+    console.log(`No plugins installed in ${scopeText}.`);
+    return;
+  }
+
+  // Sort alphabetically by plugin name
+  filteredPlugins.sort((a, b) => a.name.localeCompare(b.name));
+
+  // Group by scope for display
+  const userPlugins = filteredPlugins.filter((p) => p.scope === "user");
+  const projectPlugins = filteredPlugins.filter((p) => p.scope === "project");
+
+  // Display user scope plugins
+  if (userPlugins.length > 0) {
+    console.log("User scope:");
+    for (const plugin of userPlugins) {
+      displayPlugin(plugin, options.verbose);
+    }
+    if (projectPlugins.length > 0) {
+      console.log(""); // Add spacing between scopes
+    }
+  }
+
+  // Display project scope plugins
+  if (projectPlugins.length > 0) {
+    console.log("Project scope:");
+    for (const plugin of projectPlugins) {
+      displayPlugin(plugin, options.verbose);
+    }
+  }
+}
+
+function displayPlugin(plugin: InstalledPlugin, verbose = false) {
+  const componentCount = formatComponentCount(plugin.components);
+  const shortHash = plugin.hash.substring(0, 8);
+
+  console.log(`  ${plugin.name} [${shortHash}] (${componentCount})`);
+  console.log(`    Source: ${plugin.sourcePath}`);
+
+  if (verbose) {
+    console.log(`    Installed: ${plugin.installedAt}`);
+    console.log(`    Scope: ${plugin.scope}`);
+
+    if (plugin.components.commands.length > 0) {
+      console.log(`    Commands: ${plugin.components.commands.join(", ")}`);
+    }
+    if (plugin.components.agents.length > 0) {
+      console.log(`    Agents: ${plugin.components.agents.join(", ")}`);
+    }
+    if (plugin.components.skills.length > 0) {
+      console.log(`    Skills: ${plugin.components.skills.join(", ")}`);
+    }
+  }
+}

package/src/commands/scan.ts

@@ -0,0 +1,133 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { discoverComponents } from "../discovery";
+import { computePluginHash, resolvePluginName } from "../identity";
+import type { DiscoveredComponent } from "../types";
+
+export interface ScanOptions {
+  verbose?: boolean;
+}
+
+/**
+ * Scans a plugin directory and displays what components would be installed.
+ * This is a dry-run operation that doesn't modify any files.
+ */
+export async function scan(path: string, options: ScanOptions): Promise<void> {
+  // 1. Validate and resolve path
+  const absolutePath = resolve(path);
+
+  if (options.verbose) {
+    console.log(`[VERBOSE] Scanning path ${absolutePath}`);
+  }
+
+  if (!existsSync(absolutePath)) {
+    console.error(`Error: Directory not found: ${path}`);
+    process.exit(1);
+  }
+
+  // 2. Resolve plugin identity
+  let pluginName: string;
+  try {
+    pluginName = resolvePluginName(absolutePath);
+    if (options.verbose) {
+      console.log(`[VERBOSE] Resolved plugin name: ${pluginName}`);
+    }
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+
+  // 3. Discover components
+  const components = await discoverComponents(absolutePath, pluginName);
+
+  // 4. Compute and shorten hash
+  let hash = "";
+  try {
+    const fullHash = await computePluginHash(components);
+    hash = shortenHash(fullHash);
+
+    if (options.verbose) {
+      console.log(`[VERBOSE] Computed hash: ${fullHash} (shortened to ${hash})`);
+      console.log();
+    }
+  } catch (error) {
+    // Partial results with warning (per design decision #3)
+    console.warn(
+      `Warning: Failed to compute hash: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    hash = "????????"; // Placeholder for failed hash
+  }
+
+  // 5. Display results
+  console.log(`Scanning ${pluginName} [${hash}]...`);
+
+  if (components.length === 0) {
+    console.log();
+    console.log("No components found.");
+    console.log();
+    console.log("Expected directories:");
+    console.log("  - .opencode/command/, .claude/commands/, command/, or commands/");
+    console.log("  - .opencode/agent/, .claude/agents/, agent/, or agents/");
+    console.log("  - .opencode/skill/, .claude/skills/, skill/, or skills/");
+    return;
+  }
+
+  // Display components (matching install output format)
+  for (const component of components) {
+    const suffix = component.type === "skill" ? "/" : "";
+    console.log(`  → ${component.type}/${component.targetName}${suffix}`);
+  }
+
+  console.log();
+
+  // Display summary
+  const counts = countComponentsByType(components);
+  const summary = formatComponentCount(counts);
+  console.log(`Found ${summary}`);
+}
+
+/**
+ * Shortens a full hash to 8 characters (per SPEC).
+ */
+function shortenHash(fullHash: string): string {
+  return fullHash.substring(0, 8);
+}
+
+/**
+ * Counts components by type.
+ */
+function countComponentsByType(components: DiscoveredComponent[]): {
+  commands: number;
+  agents: number;
+  skills: number;
+} {
+  return {
+    commands: components.filter((c) => c.type === "command").length,
+    agents: components.filter((c) => c.type === "agent").length,
+    skills: components.filter((c) => c.type === "skill").length,
+  };
+}
+
+/**
+ * Formats component counts for display.
+ * Example: "1 command, 2 agents, 3 skills"
+ */
+function formatComponentCount(counts: {
+  commands: number;
+  agents: number;
+  skills: number;
+}): string {
+  const parts: string[] = [];
+
+  if (counts.commands > 0) {
+    parts.push(`${counts.commands} command${counts.commands > 1 ? "s" : ""}`);
+  }
+  if (counts.agents > 0) {
+    parts.push(`${counts.agents} agent${counts.agents > 1 ? "s" : ""}`);
+  }
+  if (counts.skills > 0) {
+    parts.push(`${counts.skills} skill${counts.skills > 1 ? "s" : ""}`);
+  }
+
+  return parts.join(", ");
+}

package/src/commands/uninstall.ts

@@ -0,0 +1,151 @@
+import { existsSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { formatComponentCount } from "../format";
+import { getComponentDir } from "../paths";
+import { getInstalledPlugin, loadRegistry, saveRegistry } from "../registry";
+import type { ComponentType, Scope } from "../types";
+
+export interface UninstallOptions {
+  scope: "user" | "project";
+  verbose?: boolean;
+}
+
+interface DeletionResult {
+  deleted: string[];
+  alreadyMissing: string[];
+}
+
+export async function uninstall(name: string, options: UninstallOptions) {
+  const { scope, verbose } = options;
+
+  try {
+    // Step 1: Look up plugin in registry
+    const plugin = await getInstalledPlugin(name, scope);
+
+    if (!plugin) {
+      throw new Error(`Plugin "${name}" is not installed in ${scope} scope.
+
+Run 'opencode-marketplace list --scope ${scope}' to see installed plugins.`);
+    }
+
+    if (verbose) {
+      console.log(`[VERBOSE] Found plugin "${name}" with hash ${plugin.hash}`);
+      console.log(
+        `[VERBOSE] Plugin has ${
+          plugin.components.commands.length +
+          plugin.components.agents.length +
+          plugin.components.skills.length
+        } components to remove`,
+      );
+    }
+
+    // Step 2: Display uninstall message with hash
+    console.log(`Uninstalling ${name} [${plugin.hash.substring(0, 8)}]...`);
+
+    // Step 3: Delete all component files/directories
+    const deletionResults: DeletionResult = {
+      deleted: [],
+      alreadyMissing: [],
+    };
+
+    // Delete commands
+    for (const command of plugin.components.commands) {
+      await deleteComponent("command", command, scope, verbose ?? false, deletionResults);
+    }
+
+    // Delete agents
+    for (const agent of plugin.components.agents) {
+      await deleteComponent("agent", agent, scope, verbose ?? false, deletionResults);
+    }
+
+    // Delete skills
+    for (const skill of plugin.components.skills) {
+      await deleteComponent("skill", skill, scope, verbose ?? false, deletionResults);
+    }
+
+    // Step 4: Update registry (remove plugin entry)
+    if (verbose) {
+      console.log(`[VERBOSE] Updating registry to remove plugin "${name}"`);
+    }
+
+    const registry = await loadRegistry(scope);
+    delete registry.plugins[name];
+    await saveRegistry(registry, scope);
+
+    if (verbose) {
+      console.log("[VERBOSE] Registry updated successfully");
+    }
+
+    // Step 5: Display success message with breakdown
+    const componentCounts = formatComponentCount(plugin.components);
+    console.log(`\nUninstalled ${name} (${componentCounts}) from ${scope} scope.`);
+
+    // Step 6: Always show warning if files were missing
+    if (deletionResults.alreadyMissing.length > 0) {
+      console.warn(
+        `\nWarning: ${deletionResults.alreadyMissing.length} component(s) were already deleted.`,
+      );
+
+      if (verbose) {
+        for (const component of deletionResults.alreadyMissing) {
+          console.warn(`  ${component}`);
+        }
+      }
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(`\nError: ${error.message}`);
+    } else {
+      console.error("\nUnknown error occurred during uninstallation");
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * Deletes a component file or directory and tracks deletion status.
+ */
+async function deleteComponent(
+  type: ComponentType,
+  componentName: string,
+  scope: Scope,
+  verbose: boolean,
+  results: DeletionResult,
+): Promise<void> {
+  const baseDir = getComponentDir(type, scope);
+  const fullPath = join(baseDir, componentName);
+
+  // Remove trailing slash for consistency
+  const normalizedPath = fullPath.endsWith("/") ? fullPath.slice(0, -1) : fullPath;
+
+  if (verbose) {
+    console.log(`[VERBOSE] Deleting ${type}/${componentName} from ${normalizedPath}`);
+  }
+
+  try {
+    if (existsSync(normalizedPath)) {
+      await rm(normalizedPath, { recursive: true, force: true });
+
+      if (!verbose) {
+        console.log(`  ✗ ${type}/${componentName}`);
+      }
+
+      results.deleted.push(`${type}/${componentName}`);
+    } else {
+      // File already deleted - not an error, but track it
+      if (!verbose) {
+        console.log(`  ⚠ ${type}/${componentName} (already deleted)`);
+      }
+
+      results.alreadyMissing.push(`${type}/${componentName}`);
+    }
+  } catch (error) {
+    // Permission denied or other filesystem error
+    throw new Error(
+      `Failed to delete ${type}/${componentName}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+}

package/src/discovery.ts

@@ -0,0 +1,94 @@
+import { existsSync } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import type { ComponentType, DiscoveredComponent } from "./types";
+import { getComponentTargetName } from "./types";
+
+const SEARCH_PATHS: Record<ComponentType, string[]> = {
+  command: [".opencode/command", ".claude/commands", "command", "commands"],
+  agent: [".opencode/agent", ".claude/agents", "agent", "agents"],
+  skill: [".opencode/skill", ".claude/skills", "skill", "skills"],
+};
+
+/**
+ * Discovers components in a plugin directory based on priority paths.
+ * Returns a flattened list of all found components.
+ */
+export async function discoverComponents(
+  pluginRoot: string,
+  pluginName: string,
+): Promise<DiscoveredComponent[]> {
+  const components: DiscoveredComponent[] = [];
+
+  // Parallelize discovery for each type
+  await Promise.all([
+    discoverType(pluginRoot, pluginName, "command", components),
+    discoverType(pluginRoot, pluginName, "agent", components),
+    discoverType(pluginRoot, pluginName, "skill", components),
+  ]);
+
+  return components;
+}
+
+async function discoverType(
+  root: string,
+  pluginName: string,
+  type: ComponentType,
+  results: DiscoveredComponent[],
+) {
+  const paths = SEARCH_PATHS[type];
+
+  // Find the first path that exists
+  for (const relativePath of paths) {
+    const fullPath = join(root, relativePath);
+
+    if (existsSync(fullPath)) {
+      await scanDirectory(fullPath, pluginName, type, results);
+      return; // Stop after first match (priority wins)
+    }
+  }
+}
+
+async function scanDirectory(
+  dirPath: string,
+  pluginName: string,
+  type: ComponentType,
+  results: DiscoveredComponent[],
+) {
+  try {
+    const entries = await readdir(dirPath);
+
+    for (const entry of entries) {
+      const entryPath = join(dirPath, entry);
+      const stats = await stat(entryPath);
+
+      if (type === "skill") {
+        // Skills must be directories containing SKILL.md
+        if (stats.isDirectory()) {
+          const skillMdPath = join(entryPath, "SKILL.md");
+          if (existsSync(skillMdPath)) {
+            results.push({
+              type,
+              sourcePath: entryPath,
+              name: entry,
+              targetName: getComponentTargetName(pluginName, entry),
+            });
+          }
+        }
+      } else {
+        // Commands and Agents must be .md files
+        if (stats.isFile() && entry.endsWith(".md")) {
+          results.push({
+            type,
+            sourcePath: entryPath,
+            name: entry,
+            targetName: getComponentTargetName(pluginName, entry),
+          });
+        }
+      }
+    }
+  } catch (_error) {
+    // Ignore errors (e.g. permission denied) to be robust
+    // In a real app we might want to log this in verbose mode
+  }
+}

package/src/format.ts

@@ -0,0 +1,27 @@
+/**
+ * Formats component counts into a human-readable string.
+ * Example: "1 command, 2 agents, 1 skill"
+ */
+export function formatComponentCount(components: {
+  commands: string[];
+  agents: string[];
+  skills: string[];
+}): string {
+  const parts: string[] = [];
+
+  if (components.commands.length > 0) {
+    parts.push(
+      `${components.commands.length} command${components.commands.length === 1 ? "" : "s"}`,
+    );
+  }
+
+  if (components.agents.length > 0) {
+    parts.push(`${components.agents.length} agent${components.agents.length === 1 ? "" : "s"}`);
+  }
+
+  if (components.skills.length > 0) {
+    parts.push(`${components.skills.length} skill${components.skills.length === 1 ? "" : "s"}`);
+  }
+
+  return parts.join(", ");
+}

package/src/identity.ts

@@ -0,0 +1,66 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { type DiscoveredComponent, validatePluginName } from "./types";
+
+/**
+ * Resolves the plugin name from the directory path.
+ * Normalizes the name to be lowercase and validates it.
+ */
+export function resolvePluginName(pluginPath: string): string {
+  // Extract the last part of the path, handling both Windows and POSIX separators
+  const parts = pluginPath.split(/[\\/]/);
+  const lastPart = parts.filter(Boolean).pop() || "";
+  const name = lastPart.toLowerCase();
+
+  if (!validatePluginName(name)) {
+    throw new Error(
+      `Invalid plugin name "${name}". Plugin names must be lowercase alphanumeric with hyphens.`,
+    );
+  }
+
+  return name;
+}
+
+/**
+ * Computes a unique hash for the plugin based on its components' content.
+ * used for versioning and change detection.
+ */
+export async function computePluginHash(components: DiscoveredComponent[]): Promise<string> {
+  const hash = createHash("sha256");
+
+  // Sort components to ensure consistent hashing
+  const sortedComponents = [...components].sort((a, b) => {
+    // Sort by type first
+    const typeCompare = a.type.localeCompare(b.type);
+    if (typeCompare !== 0) return typeCompare;
+
+    // Then by name
+    return a.name.localeCompare(b.name);
+  });
+
+  for (const component of sortedComponents) {
+    // Update hash with component identity to distinguish different components with same content
+    hash.update(`${component.type}:${component.name}:`);
+
+    try {
+      let contentPath = component.sourcePath;
+
+      if (component.type === "skill") {
+        // For skills, we only hash the SKILL.md file
+        contentPath = join(component.sourcePath, "SKILL.md");
+      }
+
+      const content = await readFile(contentPath);
+      hash.update(content);
+    } catch (error) {
+      // If a file is missing during hashing (e.g. SKILL.md missing),
+      // we throw to ensure we don't generate a valid hash for a broken plugin
+      throw new Error(
+        `Failed to read component content for hashing: ${component.sourcePath}. ${error}`,
+      );
+    }
+  }
+
+  return hash.digest("hex");
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+import { run } from "./cli";
+
+export async function main() {
+  run();
+}
+
+if (import.meta.main) {
+  main();
+}

package/src/paths.ts

@@ -0,0 +1,56 @@
+import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, normalize } from "node:path";
+import type { ComponentType, Scope } from "./types";
+import { getComponentTargetName } from "./types";
+
+/**
+ * Returns the base directory for a component type with trailing slash.
+ * Examples:
+ *   - User scope: "~/.config/opencode/command/"
+ *   - Project scope: ".opencode/command/"
+ */
+export function getComponentDir(type: ComponentType, scope: Scope): string {
+  const basePath =
+    scope === "user"
+      ? join(homedir(), ".config", "opencode", type)
+      : join(process.cwd(), ".opencode", type);
+
+  return `${normalize(basePath)}/`;
+}
+
+/**
+ * Returns the full target path for a component with plugin prefix.
+ * Handles both files (commands/agents) and directories (skills).
+ *
+ * Examples:
+ *   - Command: "~/.config/opencode/command/myplugin--reflect.md"
+ *   - Skill: "~/.config/opencode/skill/myplugin--code-review/"
+ */
+export function getComponentTargetPath(
+  pluginName: string,
+  componentName: string,
+  type: ComponentType,
+  scope: Scope,
+): string {
+  const baseDir = getComponentDir(type, scope);
+  const targetName = getComponentTargetName(pluginName, componentName);
+  const fullPath = join(baseDir, targetName);
+
+  // For skills (directories), ensure trailing slash; for files, no trailing slash
+  if (type === "skill") {
+    return `${normalize(fullPath)}/`;
+  }
+
+  return normalize(fullPath);
+}
+
+/**
+ * Ensures all component directories (command, agent, skill) exist for the given scope.
+ * Idempotent - safe to call multiple times.
+ */
+export async function ensureComponentDirsExist(scope: Scope): Promise<void> {
+  const dirs: ComponentType[] = ["command", "agent", "skill"];
+
+  await Promise.all(dirs.map((type) => mkdir(getComponentDir(type, scope), { recursive: true })));
+}

package/src/registry.ts

@@ -0,0 +1,95 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { InstalledPlugin, PluginRegistry, Scope } from "./types";
+
+/**
+ * Returns the path to the registry file for the given scope.
+ */
+export function getRegistryPath(scope: Scope): string {
+  if (scope === "user") {
+    return join(homedir(), ".config", "opencode", "plugins", "installed.json");
+  }
+  // project scope
+  return join(process.cwd(), ".opencode", "plugins", "installed.json");
+}
+
+/**
+ * Loads the plugin registry for the given scope.
+ * Returns an empty registry if the file does not exist.
+ */
+export async function loadRegistry(scope: Scope): Promise<PluginRegistry> {
+  const path = getRegistryPath(scope);
+
+  if (!existsSync(path)) {
+    return { version: 1, plugins: {} };
+  }
+
+  try {
+    const content = await readFile(path, "utf-8");
+    return JSON.parse(content);
+  } catch (error) {
+    console.error(`Error loading registry from ${path}:`, error);
+    return { version: 1, plugins: {} };
+  }
+}
+
+/**
+ * Saves the plugin registry for the given scope.
+ * Uses atomic write pattern.
+ */
+export async function saveRegistry(registry: PluginRegistry, scope: Scope): Promise<void> {
+  const path = getRegistryPath(scope);
+  const dir = join(path, "..");
+
+  if (!existsSync(dir)) {
+    await mkdir(dir, { recursive: true });
+  }
+
+  const tmpPath = `${path}.tmp`;
+  await writeFile(tmpPath, JSON.stringify(registry, null, 2), "utf-8");
+  await rename(tmpPath, path);
+}
+
+/**
+ * Gets an installed plugin by name from the specified scope.
+ */
+export async function getInstalledPlugin(
+  name: string,
+  scope: Scope,
+): Promise<InstalledPlugin | null> {
+  const registry = await loadRegistry(scope);
+  return registry.plugins[name] || null;
+}
+
+/**
+ * Gets all installed plugins. If scope is provided, only from that scope.
+ * Otherwise, combines plugins from both scopes.
+ */
+export async function getAllInstalledPlugins(scope?: Scope): Promise<InstalledPlugin[]> {
+  if (scope) {
+    const registry = await loadRegistry(scope);
+    return Object.values(registry.plugins);
+  }
+
+  // Combine user and project scopes
+  const [userRegistry, projectRegistry] = await Promise.all([
+    loadRegistry("user"),
+    loadRegistry("project"),
+  ]);
+
+  // We use a Map to handle potential duplicates (though they should be rare)
+  // preferring project scope if a plugin exists in both (unlikely but possible)
+  const allPlugins = new Map<string, InstalledPlugin>();
+
+  for (const plugin of Object.values(userRegistry.plugins)) {
+    allPlugins.set(plugin.name, plugin);
+  }
+
+  for (const plugin of Object.values(projectRegistry.plugins)) {
+    allPlugins.set(plugin.name, plugin);
+  }
+
+  return Array.from(allPlugins.values());
+}

package/src/types.ts

@@ -0,0 +1,52 @@
+export type Scope = "user" | "project";
+export type ComponentType = "command" | "agent" | "skill";
+
+export interface PluginIdentity {
+  name: string;
+  hash: string;
+}
+
+/**
+ * Represents a discovered component before installation
+ */
+export interface DiscoveredComponent {
+  type: ComponentType;
+  sourcePath: string; // absolute path
+  name: string; // original name
+  targetName: string; // prefixed name
+}
+
+export interface InstalledPlugin {
+  name: string;
+  hash: string;
+  scope: Scope;
+  sourcePath: string;
+  installedAt: string; // ISO 8601 timestamp
+  components: {
+    commands: string[]; // list of installed filenames (prefixed)
+    agents: string[]; // list of installed filenames (prefixed)
+    skills: string[]; // list of installed folder names (prefixed)
+  };
+}
+
+export interface PluginRegistry {
+  version: 1;
+  plugins: Record<string, InstalledPlugin>;
+}
+
+// Validation & Helpers
+
+/**
+ * Validates plugin name (lowercase alphanumeric and hyphens only)
+ */
+export function validatePluginName(name: string): boolean {
+  return /^[a-z0-9-]+$/.test(name);
+}
+
+/**
+ * Generates the prefixed name for a component
+ * Format: {plugin-name}--{original-name}
+ */
+export function getComponentTargetName(pluginName: string, originalName: string): string {
+  return `${pluginName}--${originalName}`;
+}