feat: detect incomplete plugins and improve install error handling

- Add IsIncomplete flag to detect plugins missing .claude-plugin/plugin.json
- Check local marketplace directory for plugin.json during plugin loading
- Show [incomplete] tag in search results with legend
- Provide actionable error messages suggesting marketplace refresh or direct use
- Skip download when valid cache exists (use cached plugin files)
- Check if plugin already installed in target scope before installing

Author: itsdevcoffee

cmd/plum/install.go

@@ -143,11 +143,30 @@ func installPlugin(pluginArg string, scope settings.Scope, projectPath string) e
 	// Check if plugin is installable via plum
 	if !pluginInfo.Installable {
 		fmt.Printf("Cannot install %s: %s\n\n", fullName, pluginInfo.InstallabilityReason)
-		fmt.Println("This plugin requires a different installation method.")
-		fmt.Println("Check the plugin's homepage for installation instructions.")
+		if pluginInfo.IsIncomplete {
+			fmt.Println("This plugin doesn't have a standard plugin manifest. You can try:")
+			fmt.Println()
+			fmt.Println("  1. Refresh your marketplace in case it was recently updated:")
+			fmt.Println("     plum marketplace refresh")
+			fmt.Println()
+			fmt.Println("  2. Use the plugin directly from the marketplace directory")
+			fmt.Println("     (Claude Code can access skills/commands without installation)")
+		} else {
+			fmt.Println("This plugin requires a different installation method.")
+			fmt.Println("Check the plugin's homepage for installation instructions.")
+		}
 		return fmt.Errorf("plugin not installable via plum")
 	}
 
+	// Check if already installed in the requested scope
+	scopeSettings, err := settings.LoadSettings(scope, projectPath)
+	if err == nil {
+		if _, exists := scopeSettings.EnabledPlugins[fullName]; exists {
+			fmt.Printf("%s is already installed in %s scope\n", fullName, scope)
+			return nil
+		}
+	}
+
 	fmt.Printf("Installing %s...\n", fullName)
 
 	// Get cache directory
@@ -156,9 +175,17 @@ func installPlugin(pluginArg string, scope settings.Scope, projectPath string) e
 		return fmt.Errorf("failed to get cache directory: %w", err)
 	}
 
-	// Download plugin files to cache
-	if err := downloadPluginToCache(pluginInfo, cacheDir); err != nil {
-		return fmt.Errorf("failed to download plugin: %w", err)
+	// Check if cache already exists with valid plugin.json
+	// This allows installation to succeed even if remote download fails
+	cacheValid := isValidPluginCache(cacheDir)
+
+	// Try to download plugin files to cache (skip if cache is valid)
+	if !cacheValid {
+		if err := downloadPluginToCache(pluginInfo, cacheDir); err != nil {
+			return fmt.Errorf("failed to download plugin: %w", err)
+		}
+	} else {
+		fmt.Println("Using cached plugin files")
 	}
 
 	// Register in installed_plugins_v2.json
@@ -184,6 +211,7 @@ type pluginSearchResult struct {
 	Source               string // Path within marketplace
 	Installable          bool   // Whether plum can install this plugin
 	InstallabilityReason string // Human-readable reason if not installable
+	IsIncomplete         bool   // True if plugin is missing required files
 }
 
 // findPluginInMarketplaces searches for a plugin across all known marketplaces
@@ -209,6 +237,7 @@ func findPluginInMarketplaces(pluginName, marketplaceFilter string) (*pluginSear
 				Source:               p.Source,
 				Installable:          p.Installable(),
 				InstallabilityReason: p.InstallabilityReason(),
+				IsIncomplete:         p.IsIncomplete,
 			})
 		}
 	}
@@ -229,6 +258,17 @@ func findPluginInMarketplaces(pluginName, marketplaceFilter string) (*pluginSear
 	return matches[0], nil
 }
 
+// isValidPluginCache checks if a cache directory contains a valid plugin.json
+func isValidPluginCache(cacheDir string) bool {
+	pluginJSONPath := filepath.Join(cacheDir, ".claude-plugin", "plugin.json")
+	info, err := os.Stat(pluginJSONPath)
+	if err != nil {
+		return false
+	}
+	// Ensure it's a file with non-zero size
+	return !info.IsDir() && info.Size() > 0
+}
+
 // pluginCacheDir returns the path to cache a plugin
 // Path: ~/.claude/plugins/cache/<marketplace>/<plugin>/
 func pluginCacheDir(marketplaceName, pluginName string) (string, error) {

cmd/plum/search.go

@@ -124,6 +124,7 @@ func outputSearchTable(results []SearchResult, query string) error {
 	hasInstalled := false
 	hasBuiltIn := false
 	hasExternal := false
+	hasIncomplete := false
 
 	// Rows
 	for _, r := range results {
@@ -146,6 +147,9 @@ func outputSearchTable(results []SearchResult, query string) error {
 		case "[external]":
 			name += " " + r.InstallabilityTag
 			hasExternal = true
+		case "[incomplete]":
+			name += " " + r.InstallabilityTag
+			hasIncomplete = true
 		}
 
 		_, _ = fmt.Fprintf(w, "%s\t%s\t%s\n", name, r.Marketplace, desc)
@@ -162,6 +166,9 @@ func outputSearchTable(results []SearchResult, query string) error {
 	if hasExternal {
 		_, _ = fmt.Fprintln(w, "[external] = external repo (install manually)")
 	}
+	if hasIncomplete {
+		_, _ = fmt.Fprintln(w, "[incomplete] = missing plugin.json (not installable)")
+	}
 
 	return w.Flush()
 }

internal/config/config.go

@@ -175,7 +175,7 @@ func LoadAllPlugins() ([]plugin.Plugin, error) {
 			}
 			seenPluginNames[mp.Name] = marketplaceName
 
-			p := convertMarketplacePlugin(mp, marketplaceName, marketplaceRepo, marketplaceSource, false, installedSet)
+			p := convertMarketplacePlugin(mp, marketplaceName, marketplaceRepo, marketplaceSource, false, installedSet, entry.InstallLocation)
 			plugins = append(plugins, p)
 		}
 	}
@@ -204,7 +204,8 @@ func LoadAllPlugins() ([]plugin.Plugin, error) {
 			}
 			seenPluginNames[mp.Name] = marketplaceName
 
-			p := convertMarketplacePlugin(mp, marketplaceName, disc.Repo, disc.Source, true, installedSet)
+			// Discovered marketplaces don't have local paths - pass empty string
+			p := convertMarketplacePlugin(mp, marketplaceName, disc.Repo, disc.Source, true, installedSet, "")
 			plugins = append(plugins, p)
 		}
 	}
@@ -213,17 +214,36 @@ func LoadAllPlugins() ([]plugin.Plugin, error) {
 }
 
 // convertMarketplacePlugin converts a MarketplacePlugin to a Plugin.
+// marketplacePath is the local path to the marketplace directory (empty for discovered marketplaces).
 func convertMarketplacePlugin(
 	mp marketplace.MarketplacePlugin,
 	marketplaceName string,
 	marketplaceRepo string,
 	marketplaceSource string,
 	isDiscoverable bool,
 	installedSet map[string]PluginInstall,
+	marketplacePath string,
 ) plugin.Plugin {
 	fullName := mp.Name + "@" + marketplaceName
 	install, isInstalled := installedSet[fullName]
 
+	// Check if plugin is incomplete (missing .claude-plugin/plugin.json)
+	// Only check for locally installed marketplaces, not discovered ones
+	isIncomplete := mp.IsIncomplete
+	if !isIncomplete && marketplacePath != "" && !mp.HasLSPServers && !mp.IsExternalURL {
+		// Construct path to plugin.json based on source
+		sourcePath := mp.Source
+		if sourcePath == "" {
+			sourcePath = "plugins/" + mp.Name
+		} else if len(sourcePath) > 2 && sourcePath[:2] == "./" {
+			sourcePath = sourcePath[2:]
+		}
+		pluginJSONPath := filepath.Join(marketplacePath, sourcePath, ".claude-plugin", "plugin.json")
+		if _, err := os.Stat(pluginJSONPath); os.IsNotExist(err) {
+			isIncomplete = true
+		}
+	}
+
 	p := plugin.Plugin{
 		Name:        mp.Name,
 		Description: mp.Description,
@@ -248,6 +268,7 @@ func convertMarketplacePlugin(
 		Tags:              mp.Tags,
 		HasLSPServers:     mp.HasLSPServers,
 		IsExternalURL:     mp.IsExternalURL,
+		IsIncomplete:      isIncomplete,
 	}
 
 	if isInstalled {

internal/marketplace/types.go

@@ -39,15 +39,16 @@ type MarketplacePlugin struct {
 	Tags        []string `json:"tags"`
 	Strict      bool     `json:"strict"`
 
-	// Installability tracking (set during unmarshaling)
+	// Installability tracking (set during unmarshaling or validation)
 	HasLSPServers bool `json:"-"` // True if plugin has lspServers config (built into Claude Code)
 	IsExternalURL bool `json:"-"` // True if source points to external Git repo
+	IsIncomplete  bool `json:"-"` // True if plugin is missing required files (e.g., .claude-plugin/plugin.json)
 }
 
 // Installable returns true if the plugin can be installed via plum.
-// Plugins with LSP servers or external URLs require different installation methods.
+// Plugins with LSP servers, external URLs, or missing files require different installation methods.
 func (mp *MarketplacePlugin) Installable() bool {
-	return !mp.HasLSPServers && !mp.IsExternalURL
+	return !mp.HasLSPServers && !mp.IsExternalURL && !mp.IsIncomplete
 }
 
 // InstallabilityReason returns a human-readable reason why the plugin is not installable.
@@ -58,6 +59,8 @@ func (mp *MarketplacePlugin) InstallabilityReason() string {
 		return "LSP plugin (built into Claude Code)"
 	case mp.IsExternalURL:
 		return "external repository (requires manual installation)"
+	case mp.IsIncomplete:
+		return "incomplete plugin (missing .claude-plugin/plugin.json)"
 	default:
 		return ""
 	}
@@ -71,6 +74,8 @@ func (mp *MarketplacePlugin) InstallabilityTag() string {
 		return "[built-in]"
 	case mp.IsExternalURL:
 		return "[external]"
+	case mp.IsIncomplete:
+		return "[incomplete]"
 	default:
 		return ""
 	}

internal/marketplace/types_test.go

@@ -196,6 +196,26 @@ func TestMarketplacePlugin_UnmarshalJSON_NullLSPServers(t *testing.T) {
 	}
 }
 
+func TestMarketplacePlugin_IncompletePlugin(t *testing.T) {
+	// IsIncomplete is set externally during plugin loading, not unmarshaling
+	plugin := MarketplacePlugin{
+		Name:         "incomplete-plugin",
+		Source:       "./plugins/incomplete",
+		Description:  "An incomplete plugin",
+		IsIncomplete: true, // Set manually (normally done during loading)
+	}
+
+	if plugin.Installable() {
+		t.Error("expected plugin to NOT be installable (incomplete)")
+	}
+	if plugin.InstallabilityReason() != "incomplete plugin (missing .claude-plugin/plugin.json)" {
+		t.Errorf("unexpected installability reason: %q", plugin.InstallabilityReason())
+	}
+	if plugin.InstallabilityTag() != "[incomplete]" {
+		t.Errorf("unexpected installability tag: %q", plugin.InstallabilityTag())
+	}
+}
+
 func TestMarketplaceManifest_UnmarshalJSON(t *testing.T) {
 	jsonData := `{
 		"name": "test-marketplace",

internal/plugin/plugin.go

@@ -30,12 +30,13 @@ type Plugin struct {
 	// Installability tracking
 	HasLSPServers bool `json:"-"` // True if plugin has lspServers config (built into Claude Code)
 	IsExternalURL bool `json:"-"` // True if source points to external Git repo
+	IsIncomplete  bool `json:"-"` // True if plugin is missing required files (e.g., .claude-plugin/plugin.json)
 }
 
 // Installable returns true if the plugin can be installed via plum.
-// Plugins with LSP servers or external URLs require different installation methods.
+// Plugins with LSP servers, external URLs, or missing files require different installation methods.
 func (p Plugin) Installable() bool {
-	return !p.HasLSPServers && !p.IsExternalURL
+	return !p.HasLSPServers && !p.IsExternalURL && !p.IsIncomplete
 }
 
 // InstallabilityReason returns a human-readable reason why the plugin is not installable.
@@ -46,6 +47,8 @@ func (p Plugin) InstallabilityReason() string {
 		return "LSP plugin (built into Claude Code)"
 	case p.IsExternalURL:
 		return "external repository (requires manual installation)"
+	case p.IsIncomplete:
+		return "incomplete plugin (missing .claude-plugin/plugin.json)"
 	default:
 		return ""
 	}
@@ -59,6 +62,8 @@ func (p Plugin) InstallabilityTag() string {
 		return "[built-in]"
 	case p.IsExternalURL:
 		return "[external]"
+	case p.IsIncomplete:
+		return "[incomplete]"
 	default:
 		return ""
 	}