opencode-marketplace 0.1.0 → 0.2.0

package/README.md

@@ -1,18 +1,15 @@
 # OpenCode Marketplace
 
-CLI marketplace for OpenCode plugins - declarative, file-based plugin distribution for commands, agents, and skills.
+CLI for installing OpenCode plugins from local directories or GitHub repositories.
 
-## Overview
+## Features
 
-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
+- 📦 Install from **local directories** or **GitHub URLs**
+- 🔄 **Update** remote plugins with one command
+- 🎯 **Zero-config** convention-based discovery
+- 🔐 **Content-hash** based change detection
+- 🎭 Support for **commands**, **agents**, and **skills**
+- 🌍 **User-global** or **project-local** scope
 
 ## Installation
 
@@ -28,91 +25,71 @@ bun install -g opencode-marketplace
 
 ## Quick Start
 
-### Install a Plugin
-
 ```bash
+# Install from local directory
 opencode-marketplace install /path/to/my-plugin
-```
 
-### List Installed Plugins
+# Install from GitHub
+opencode-marketplace install https://github.com/user/repo
 
-```bash
-opencode-marketplace list
-```
+# Install from subfolder
+opencode-marketplace install https://github.com/user/repo/tree/main/plugins/foo
 
-### Scan a Plugin (Dry Run)
+# Update a remote plugin
+opencode-marketplace update my-plugin
 
-```bash
-opencode-marketplace scan /path/to/my-plugin
-```
+# List installed plugins
+opencode-marketplace list
 
-### Uninstall a Plugin
+# Scan before installing (dry-run)
+opencode-marketplace scan https://github.com/user/repo
 
-```bash
+# Uninstall
 opencode-marketplace uninstall my-plugin
 ```
 
 ## Plugin Structure
 
-A plugin is a directory containing components in well-known locations:
+A plugin is a directory with components in well-known locations:
 
 ```
 my-plugin/
-├── command/           # or .opencode/command/, .claude/commands/
+├── command/         # or .opencode/command/, .claude/commands/
 │   └── reflect.md
-├── agent/            # or .opencode/agent/, .claude/agents/
+├── agent/          # or .opencode/agent/, .claude/agents/
 │   └── reviewer.md
-└── skill/            # or .opencode/skill/, .claude/skills/
+└── skill/          # or .opencode/skill/, .claude/skills/
     └── code-review/
         ├── SKILL.md
-        └── data.json
+        └── reference.md
 ```
 
-### 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/` |
+**Discovery Priority:** `.opencode/*` → `.claude/*` → `./command/` → `./commands/`
 
 ## 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.
+1. **Discovery** - Scans for components using convention-based paths
+2. **Namespacing** - Copies files with prefixes: `my-plugin--reflect.md`
+3. **Registry** - Tracks installations in `~/.config/opencode/plugins/installed.json`
+4. **Change Detection** - Content hashing detects actual changes
 
 ## Scopes
 
-| Scope | Target Location | Registry |
-|-------|----------------|----------|
+| Scope | Target | Registry |
+|-------|--------|----------|
 | `user` (default) | `~/.config/opencode/` | `~/.config/opencode/plugins/installed.json` |
 | `project` | `.opencode/` | `.opencode/plugins/installed.json` |
 
-## Example
+Use `--scope project` for project-local installations.
+
+## Example Output
 
 ```bash
-$ opencode-marketplace install ~/plugins/misc
+$ opencode-marketplace install https://github.com/user/awesome-plugins/tree/main/misc
 
 Installing misc [a1b2c3d4]...
   → command/misc--reflect.md
-  → skill/misc--git-review/
+  → skill/misc--review/
 
 Installed misc (1 command, 1 skill) to user scope.
 ```
@@ -120,62 +97,20 @@ Installed misc (1 command, 1 skill) to user scope.
 ```bash
 $ opencode-marketplace list
 
-Installed plugins (user scope):
+User scope:
   misc [a1b2c3d4] (1 command, 1 skill)
-    Source: /home/user/plugins/misc
+    Source: https://github.com/user/awesome-plugins/tree/main/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
+bun install          # Install dependencies
+bun run dev          # Run locally
+bun test             # Run tests
+bun run lint         # Lint code
 ```
 
-## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-marketplace",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CLI marketplace for OpenCode plugins",
   "type": "module",
   "author": "nikiforovall",

package/src/cli.ts

@@ -4,12 +4,13 @@ import { install } from "./commands/install";
 import { list } from "./commands/list";
 import { scan } from "./commands/scan";
 import { uninstall } from "./commands/uninstall";
+import { update } from "./commands/update";
 
 export function run(argv = process.argv) {
   const cli = cac("opencode-marketplace");
 
   cli
-    .command("install <path>", "Install a plugin from a local directory")
+    .command("install <path>", "Install a plugin from a local directory or GitHub URL")
     .option("--scope <scope>", "Installation scope (user/project)", { default: "user" })
     .option("--force", "Overwrite existing components", { default: false })
     .action((path, options) => {
@@ -43,11 +44,22 @@ export function run(argv = process.argv) {
     });
 
   cli
-    .command("scan <path>", "Scan a directory for plugin components (dry-run)")
+    .command("scan <path>", "Scan a local directory or GitHub URL for plugin components (dry-run)")
     .action((path, options) => {
       return scan(path, options);
     });
 
+  cli
+    .command("update <name>", "Update a plugin from its remote source")
+    .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 update(name, options);
+    });
+
   // Global options
   cli.option("--verbose", "Enable verbose logging");
 

package/src/commands/install.ts

@@ -3,10 +3,19 @@ import { copyFile, cp, mkdir } from "node:fs/promises";
 import { basename, dirname, resolve } from "node:path";
 import { discoverComponents } from "../discovery";
 import { formatComponentCount } from "../format";
+import { cleanup, cloneToTemp } from "../git";
+import { isGitHubUrl, parseGitHubUrl } from "../github";
 import { computePluginHash, resolvePluginName } from "../identity";
 import { ensureComponentDirsExist, getComponentTargetPath } from "../paths";
 import { getInstalledPlugin, loadRegistry, saveRegistry } from "../registry";
-import type { ComponentType, DiscoveredComponent, InstalledPlugin, Scope } from "../types";
+import type {
+  ComponentType,
+  DiscoveredComponent,
+  InstalledPlugin,
+  PluginSource,
+  Scope,
+} from "../types";
+import { validatePluginName } from "../types";
 
 export interface InstallOptions {
   scope: "user" | "project";
@@ -23,15 +32,74 @@ interface ConflictInfo {
 export async function install(path: string, options: InstallOptions) {
   const { scope, force, verbose } = options;
 
+  let tempDir: string | null = null;
+  let pluginSource: PluginSource;
+
   try {
-    // Step 1: Validate plugin directory exists
-    const pluginPath = resolve(path);
-    if (!existsSync(pluginPath)) {
-      throw new Error(`Plugin directory not found: ${path}`);
+    // Step 1: Detect if path is a GitHub URL or local path
+    let pluginPath: string;
+
+    if (isGitHubUrl(path)) {
+      // Remote installation
+      const parsed = parseGitHubUrl(path);
+      if (!parsed) {
+        throw new Error(`Invalid GitHub URL: ${path}`);
+      }
+
+      if (verbose) {
+        console.log(
+          `[VERBOSE] Cloning from GitHub: ${parsed.owner}/${parsed.repo}${parsed.ref ? `@${parsed.ref}` : ""}`,
+        );
+      }
+
+      // Clone repository - use base URL without /tree/ path
+      const repoUrl = `https://github.com/${parsed.owner}/${parsed.repo}.git`;
+      const cloneResult = await cloneToTemp(repoUrl, parsed.ref, parsed.subpath);
+      tempDir = cloneResult.tempDir;
+
+      // Plugin path from clone result
+      pluginPath = cloneResult.pluginPath;
+
+      pluginSource = {
+        type: "remote",
+        url: path,
+        ref: parsed.ref,
+      };
+    } else {
+      // Local installation
+      pluginPath = resolve(path);
+      if (!existsSync(pluginPath)) {
+        throw new Error(`Plugin directory not found: ${path}`);
+      }
+
+      pluginSource = {
+        type: "local",
+        path: pluginPath,
+      };
     }
 
     // Step 2: Resolve plugin identity
-    const pluginName = resolvePluginName(pluginPath);
+    // For remote installations, derive name from URL instead of temp directory
+    let pluginName: string;
+    if (pluginSource.type === "remote") {
+      const parsed = parseGitHubUrl(path);
+      if (!parsed) {
+        throw new Error(`Invalid GitHub URL: ${path}`);
+      }
+      // Use subpath if present (e.g., "foo" from "plugins/foo"), otherwise use repo name
+      const lastPathPart = parsed.subpath?.split("/").filter(Boolean).pop();
+      pluginName = (lastPathPart || parsed.repo).toLowerCase();
+
+      // Validate the derived name
+      if (!validatePluginName(pluginName)) {
+        throw new Error(
+          `Invalid plugin name "${pluginName}" derived from URL. Plugin names must be lowercase alphanumeric with hyphens.`,
+        );
+      }
+    } else {
+      pluginName = resolvePluginName(pluginPath);
+    }
+
     if (verbose) {
       console.log(`[VERBOSE] Resolved plugin name: ${pluginName}`);
     }
@@ -144,7 +212,7 @@ export async function install(path: string, options: InstallOptions) {
       name: pluginName,
       hash: pluginHash,
       scope,
-      sourcePath: pluginPath,
+      source: pluginSource,
       installedAt: new Date().toISOString(),
       components: installedComponents,
     };
@@ -152,10 +220,20 @@ export async function install(path: string, options: InstallOptions) {
     registry.plugins[pluginName] = newPlugin;
     await saveRegistry(registry, scope);
 
-    // Step 10: Print success message
+    // Step 10: Cleanup temp directory if remote installation
+    if (tempDir) {
+      await cleanup(tempDir);
+    }
+
+    // Step 11: Print success message
     const componentCounts = formatComponentCount(installedComponents);
     console.log(`\nInstalled ${pluginName} (${componentCounts}) to ${scope} scope.`);
   } catch (error) {
+    // Cleanup temp directory on error
+    if (tempDir) {
+      await cleanup(tempDir);
+    }
+
     if (error instanceof Error) {
       console.error(`\nError: ${error.message}`);
     } else {

package/src/commands/list.ts

@@ -57,7 +57,10 @@ function displayPlugin(plugin: InstalledPlugin, verbose = false) {
   const shortHash = plugin.hash.substring(0, 8);
 
   console.log(`  ${plugin.name} [${shortHash}] (${componentCount})`);
-  console.log(`    Source: ${plugin.sourcePath}`);
+
+  // Display source based on type
+  const sourceText = plugin.source.type === "remote" ? plugin.source.url : plugin.source.path;
+  console.log(`    Source: ${sourceText}`);
 
   if (verbose) {
     console.log(`    Installed: ${plugin.installedAt}`);

package/src/commands/scan.ts

@@ -1,8 +1,11 @@
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { discoverComponents } from "../discovery";
+import { cleanup, cloneToTemp } from "../git";
+import { isGitHubUrl, parseGitHubUrl } from "../github";
 import { computePluginHash, resolvePluginName } from "../identity";
 import type { DiscoveredComponent } from "../types";
+import { validatePluginName } from "../types";
 
 export interface ScanOptions {
   verbose?: boolean;
@@ -13,77 +16,129 @@ export interface ScanOptions {
  * 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);
+  let tempDir: string | null = null;
 
-  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}`);
+    // 1. Detect if path is a GitHub URL or local path
+    let absolutePath: string;
+
+    if (isGitHubUrl(path)) {
+      // Remote scan
+      const parsed = parseGitHubUrl(path);
+      if (!parsed) {
+        console.error(`Error: Invalid GitHub URL: ${path}`);
+        process.exit(1);
+      }
+
+      if (options.verbose) {
+        console.log(
+          `[VERBOSE] Cloning from GitHub: ${parsed.owner}/${parsed.repo}${parsed.ref ? `@${parsed.ref}` : ""}`,
+        );
+      }
+
+      // Clone repository - use base URL without /tree/ path
+      const repoUrl = `https://github.com/${parsed.owner}/${parsed.repo}.git`;
+      const cloneResult = await cloneToTemp(repoUrl, parsed.ref, parsed.subpath);
+      tempDir = cloneResult.tempDir;
+      absolutePath = cloneResult.pluginPath;
+    } else {
+      // Local scan
+      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);
+      }
     }
-  } catch (error) {
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exit(1);
-  }
 
-  // 3. Discover components
-  const components = await discoverComponents(absolutePath, pluginName);
+    // 2. Resolve plugin identity
+    let pluginName: string;
+    try {
+      // For remote scans, derive name from URL instead of temp directory
+      if (isGitHubUrl(path)) {
+        const parsed = parseGitHubUrl(path);
+        if (!parsed) {
+          throw new Error(`Invalid GitHub URL: ${path}`);
+        }
+        // Use subpath if present (e.g., "foo" from "plugins/foo"), otherwise use repo name
+        const lastPathPart = parsed.subpath?.split("/").filter(Boolean).pop();
+        pluginName = (lastPathPart || parsed.repo).toLowerCase();
+
+        // Validate the derived name
+        if (!validatePluginName(pluginName)) {
+          throw new Error(
+            `Invalid plugin name "${pluginName}" derived from URL. Plugin names must be lowercase alphanumeric with hyphens.`,
+          );
+        }
+      } else {
+        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);
+    }
 
-  // 4. Compute and shorten hash
-  let hash = "";
-  try {
-    const fullHash = await computePluginHash(components);
-    hash = shortenHash(fullHash);
+    // 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 (options.verbose) {
-      console.log(`[VERBOSE] Computed hash: ${fullHash} (shortened to ${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;
     }
-  } 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}]...`);
+    // Display components (matching install output format)
+    for (const component of components) {
+      const suffix = component.type === "skill" ? "/" : "";
+      console.log(`  → ${component.type}/${component.targetName}${suffix}`);
+    }
 
-  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}`);
+    // Display summary
+    const counts = countComponentsByType(components);
+    const summary = formatComponentCount(counts);
+    console.log(`Found ${summary}`);
+  } finally {
+    // Cleanup temp directory if remote scan
+    if (tempDir) {
+      await cleanup(tempDir);
+    }
   }
-
-  console.log();
-
-  // Display summary
-  const counts = countComponentsByType(components);
-  const summary = formatComponentCount(counts);
-  console.log(`Found ${summary}`);
 }
 
 /**

package/src/commands/update.ts

@@ -0,0 +1,97 @@
+import { discoverComponents } from "../discovery";
+import { cleanup, cloneToTemp } from "../git";
+import { parseGitHubUrl } from "../github";
+import { computePluginHash } from "../identity";
+import { getInstalledPlugin } from "../registry";
+import { install } from "./install";
+
+export interface UpdateOptions {
+  scope: "user" | "project";
+  verbose?: boolean;
+}
+
+export async function update(pluginName: string, options: UpdateOptions) {
+  const { scope, verbose } = options;
+
+  try {
+    // Step 1: Look up plugin in registry
+    const plugin = await getInstalledPlugin(pluginName, scope);
+
+    if (!plugin) {
+      throw new Error(
+        `Plugin "${pluginName}" is not installed in ${scope} scope. Use 'list' to see installed plugins.`,
+      );
+    }
+
+    // Step 2: Check if it's a remote plugin
+    if (plugin.source.type === "local") {
+      throw new Error(
+        `Cannot update local plugin "${pluginName}". Local plugins must be updated at their source and reinstalled.`,
+      );
+    }
+
+    // Step 3: Re-fetch from remote
+    const { url, ref } = plugin.source;
+
+    console.log(`Fetching ${url}...`);
+
+    const parsed = parseGitHubUrl(url);
+    if (!parsed) {
+      throw new Error(`Invalid GitHub URL in registry: ${url}`);
+    }
+
+    let tempDir: string | null = null;
+
+    try {
+      // Clone repository - use base URL without /tree/ path
+      const repoUrl = `https://github.com/${parsed.owner}/${parsed.repo}.git`;
+      const cloneResult = await cloneToTemp(repoUrl, parsed.ref || ref, parsed.subpath);
+      tempDir = cloneResult.tempDir;
+
+      if (verbose) {
+        console.log(`[VERBOSE] Cloned to ${tempDir}`);
+      }
+
+      // Step 4: Compute new hash
+      const components = await discoverComponents(cloneResult.pluginPath, pluginName);
+      const newHash = await computePluginHash(components);
+
+      // Step 5: Check if already up to date
+      if (newHash === plugin.hash) {
+        console.log(`\nPlugin ${pluginName} is already up to date [${newHash.substring(0, 8)}].`);
+        return;
+      }
+
+      if (verbose) {
+        console.log(
+          `[VERBOSE] Hash changed: ${plugin.hash.substring(0, 8)} → ${newHash.substring(0, 8)}`,
+        );
+      }
+
+      // Step 6: Run install flow (will overwrite existing)
+      // Cleanup temp before install takes over
+      const _pluginPath = cloneResult.pluginPath;
+      const tmpToKeep = tempDir;
+      tempDir = null; // Prevent cleanup in finally
+
+      console.log(`\nUpdating ${pluginName}...`);
+
+      // Use install command directly
+      await install(url, { scope, force: true, verbose });
+
+      // Cleanup after install
+      await cleanup(tmpToKeep);
+    } finally {
+      if (tempDir) {
+        await cleanup(tempDir);
+      }
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(`\nError: ${error.message}`);
+    } else {
+      console.error("\nUnknown error occurred during update");
+    }
+    process.exit(1);
+  }
+}

package/src/git.ts

@@ -0,0 +1,75 @@
+/**
+ * Git operations for cloning remote repositories
+ */
+
+import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export interface CloneResult {
+  tempDir: string; // temp clone location
+  pluginPath: string; // actual plugin directory (tempDir + subpath)
+}
+
+/**
+ * Clones a Git repository to a temporary directory.
+ *
+ * @param url - Git repository URL
+ * @param ref - Optional branch, tag, or commit to checkout
+ * @param subpath - Optional subfolder path within the repository
+ * @returns Clone result with temp directory and plugin path
+ * @throws Error if clone fails
+ */
+export async function cloneToTemp(
+  url: string,
+  ref?: string,
+  subpath?: string,
+): Promise<CloneResult> {
+  // Generate unique temp directory
+  const tempDir = join(tmpdir(), `opencode-plugin-${randomUUID()}`);
+
+  // Build git clone command
+  const args = ["clone", "--depth", "1"];
+
+  if (ref) {
+    args.push("--branch", ref);
+  }
+
+  args.push(url, tempDir);
+
+  // Execute git clone
+  const result = spawnSync("git", args, {
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+  });
+
+  if (result.error) {
+    throw new Error(`Git command failed: ${result.error.message}`);
+  }
+
+  if (result.status !== 0) {
+    const errorMessage = result.stderr || result.stdout || "Unknown error";
+    throw new Error(`Failed to clone repository: ${errorMessage.trim()}`);
+  }
+
+  // Determine actual plugin path
+  const pluginPath = subpath ? join(tempDir, subpath) : tempDir;
+
+  return { tempDir, pluginPath };
+}
+
+/**
+ * Removes a temporary directory.
+ *
+ * @param tempDir - Path to temporary directory to remove
+ */
+export async function cleanup(tempDir: string): Promise<void> {
+  try {
+    await rm(tempDir, { recursive: true, force: true });
+  } catch (_error) {
+    // Ignore cleanup errors (temp dir will be cleaned eventually by OS)
+    console.warn(`Warning: Failed to cleanup temp directory ${tempDir}`);
+  }
+}

package/src/github.ts

@@ -0,0 +1,100 @@
+/**
+ * GitHub URL parsing utilities
+ */
+
+export interface GitHubSource {
+  owner: string;
+  repo: string;
+  ref?: string; // branch, tag, or commit
+  subpath?: string; // subfolder path
+}
+
+/**
+ * Parses a GitHub URL into structured components.
+ *
+ * Supported formats:
+ * - https://github.com/user/repo
+ * - https://github.com/user/repo/tree/main
+ * - https://github.com/user/repo/tree/main/plugins/foo
+ * - https://github.com/user/repo/tree/v1.0.0/src
+ *
+ * @param url - GitHub URL to parse
+ * @returns Parsed GitHub source or null if invalid
+ */
+export function parseGitHubUrl(url: string): GitHubSource | null {
+  try {
+    const parsed = new URL(url);
+
+    // Validate it's a GitHub URL
+    if (parsed.hostname !== "github.com") {
+      return null;
+    }
+
+    // Extract path segments (remove leading slash)
+    const pathSegments = parsed.pathname.slice(1).split("/").filter(Boolean);
+
+    // Need at least owner/repo
+    if (pathSegments.length < 2) {
+      return null;
+    }
+
+    const [owner, repo, ...rest] = pathSegments;
+
+    // Basic case: https://github.com/owner/repo
+    if (rest.length === 0) {
+      return { owner, repo };
+    }
+
+    // Check for /tree/ or /blob/ segment
+    const treeOrBlobIndex =
+      rest.indexOf("tree") !== -1 ? rest.indexOf("tree") : rest.indexOf("blob");
+
+    if (treeOrBlobIndex === -1) {
+      // No tree/blob segment, treat rest as invalid
+      return null;
+    }
+
+    // Format: /tree/<ref>/subpath or /tree/<ref>
+    const ref = rest[treeOrBlobIndex + 1];
+    const subpathSegments = rest.slice(treeOrBlobIndex + 2);
+
+    if (!ref) {
+      return null;
+    }
+
+    const result: GitHubSource = { owner, repo, ref };
+
+    if (subpathSegments.length > 0) {
+      result.subpath = subpathSegments.join("/");
+    }
+
+    return result;
+  } catch {
+    // Invalid URL
+    return null;
+  }
+}
+
+/**
+ * Checks if a string is a GitHub URL
+ */
+export function isGitHubUrl(input: string): boolean {
+  return input.startsWith("https://github.com/");
+}
+
+/**
+ * Reconstructs a full GitHub URL from parsed components
+ */
+export function buildGitHubUrl(source: GitHubSource): string {
+  let url = `https://github.com/${source.owner}/${source.repo}`;
+
+  if (source.ref) {
+    url += `/tree/${source.ref}`;
+
+    if (source.subpath) {
+      url += `/${source.subpath}`;
+    }
+  }
+
+  return url;
+}

package/src/registry.ts

@@ -23,15 +23,23 @@ export async function loadRegistry(scope: Scope): Promise<PluginRegistry> {
   const path = getRegistryPath(scope);
 
   if (!existsSync(path)) {
-    return { version: 1, plugins: {} };
+    return { version: 2, plugins: {} };
   }
 
   try {
     const content = await readFile(path, "utf-8");
-    return JSON.parse(content);
+    const registry = JSON.parse(content);
+
+    // If old v1 registry, warn and return empty
+    if (registry.version === 1) {
+      console.warn("Warning: Registry v1 detected. Please reinstall plugins for v2 compatibility.");
+      return { version: 2, plugins: {} };
+    }
+
+    return registry;
   } catch (error) {
     console.error(`Error loading registry from ${path}:`, error);
-    return { version: 1, plugins: {} };
+    return { version: 2, plugins: {} };
   }
 }
 

package/src/types.ts

@@ -16,11 +16,18 @@ export interface DiscoveredComponent {
   targetName: string; // prefixed name
 }
 
+/**
+ * Source of a plugin - either local path or remote URL
+ */
+export type PluginSource =
+  | { type: "local"; path: string }
+  | { type: "remote"; url: string; ref?: string };
+
 export interface InstalledPlugin {
   name: string;
   hash: string;
   scope: Scope;
-  sourcePath: string;
+  source: PluginSource;
   installedAt: string; // ISO 8601 timestamp
   components: {
     commands: string[]; // list of installed filenames (prefixed)
@@ -30,7 +37,7 @@ export interface InstalledPlugin {
 }
 
 export interface PluginRegistry {
-  version: 1;
+  version: 1 | 2;
   plugins: Record<string, InstalledPlugin>;
 }