merge: resolve conflicts with main (PR #329 merged)

Both branches made equivalent fixes to shared wfctl files. Resolved
by taking main's versions for shared code (plugin_install, lockfile,
registry_source, generator, docs) while preserving engine-branch-only
additions (integrity, autofetch, engine auto-fetch, config).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: intel352

cmd/wfctl/multi_registry.go

@@ -29,12 +29,12 @@ func NewMultiRegistry(cfg *RegistryConfig) *MultiRegistry {
 		case "github":
 			sources = append(sources, NewGitHubRegistrySource(sc))
 		case "static":
-			src, err := NewStaticRegistrySource(sc)
-			if err != nil {
-				fmt.Fprintf(os.Stderr, "warning: %v, skipping\n", err)
+			staticSrc, staticErr := NewStaticRegistrySource(sc)
+			if staticErr != nil {
+				fmt.Fprintf(os.Stderr, "warning: %v, skipping\n", staticErr)
 				continue
 			}
-			sources = append(sources, src)
+			sources = append(sources, staticSrc)
 		default:
 			// Skip unknown types
 			fmt.Fprintf(os.Stderr, "warning: unknown registry type %q for %q, skipping\n", sc.Type, sc.Name)

cmd/wfctl/multi_registry_test.go

@@ -184,7 +184,7 @@ func TestLoadRegistryConfigFromFile(t *testing.T) {
 }
 
 func TestLoadRegistryConfigDefault(t *testing.T) {
-	// Test DefaultRegistryConfig directly to avoid picking up user config files.
+	// Test DefaultRegistryConfig directly.
 	cfg := DefaultRegistryConfig()
 	if len(cfg.Registries) != 2 {
 		t.Fatalf("expected 2 registries (static + github fallback), got %d", len(cfg.Registries))
@@ -197,6 +197,25 @@ func TestLoadRegistryConfigDefault(t *testing.T) {
 	}
 }
 
+func TestLoadRegistryConfigFallback(t *testing.T) {
+	// LoadRegistryConfig with no valid config files should fall back to
+	// DefaultRegistryConfig. Isolate from real config by changing both
+	// CWD and HOME to a temp dir.
+	origDir, _ := os.Getwd()
+	tmpDir := t.TempDir()
+	_ = os.Chdir(tmpDir)
+	t.Setenv("HOME", tmpDir)
+	t.Cleanup(func() { _ = os.Chdir(origDir) })
+
+	cfg, err := LoadRegistryConfig(filepath.Join(tmpDir, "nonexistent.yaml"))
+	if err != nil {
+		t.Fatalf("LoadRegistryConfig: %v", err)
+	}
+	if len(cfg.Registries) != 2 {
+		t.Fatalf("expected 2 registries (default fallback), got %d", len(cfg.Registries))
+	}
+}
+
 func TestSaveAndLoadRegistryConfig(t *testing.T) {
 	dir := t.TempDir()
 	cfgPath := filepath.Join(dir, "wfctl", "config.yaml")

cmd/wfctl/plugin_install.go

@@ -74,26 +74,26 @@ func runPluginInstall(args []string) error {
 	directURL := fs.String("url", "", "Install from a direct download URL (tar.gz archive)")
 	localPath := fs.String("local", "", "Install from a local plugin directory")
 	fs.Usage = func() {
-		fmt.Fprintf(fs.Output(), "Usage: wfctl plugin install [options] [<name>[@<version>]]\n\nInstall a plugin from the registry, a URL, a local directory, or from the lockfile.\n\n  wfctl plugin install <name>         Install latest from registry\n  wfctl plugin install <name>@<ver>   Install specific version\n  wfctl plugin install --url <url>    Install from direct URL\n  wfctl plugin install --local <dir>  Install from local directory\n  wfctl plugin install                Install all from .wfctl.yaml\n\nOptions:\n")
+		fmt.Fprintf(fs.Output(), "Usage: wfctl plugin install [options] [<name>[@<version>]]\n\nInstall a plugin from the registry, a URL, a local directory, or from the lockfile.\n\n  wfctl plugin install <name>         Install latest from registry\n  wfctl plugin install <name>@v1.0.0  Install specific version\n  wfctl plugin install --url <url>     Install from a direct download URL\n  wfctl plugin install --local <dir>   Install from a local build directory\n  wfctl plugin install                 Install all plugins from .wfctl.yaml\n\nOptions:\n")
 		fs.PrintDefaults()
 	}
 	if err := fs.Parse(args); err != nil {
 		return err
 	}
 
-	// Validate mutual exclusivity of install modes.
-	modes := 0
+	// Enforce mutual exclusivity: at most one of --url, --local, or positional args.
+	exclusiveCount := 0
 	if *directURL != "" {
-		modes++
+		exclusiveCount++
 	}
 	if *localPath != "" {
-		modes++
+		exclusiveCount++
 	}
 	if fs.NArg() > 0 {
-		modes++
+		exclusiveCount++
 	}
-	if modes > 1 {
-		return fmt.Errorf("specify only one of: <name>, --url, or --local")
+	if exclusiveCount > 1 {
+		return fmt.Errorf("--url, --local, and <name> are mutually exclusive; specify only one")
 	}
 
 	if *directURL != "" {
@@ -110,7 +110,8 @@ func runPluginInstall(args []string) error {
 	}
 
 	nameArg := fs.Arg(0)
-	pluginName, _ := parseNameVersion(nameArg)
+	rawName, _ := parseNameVersion(nameArg)
+	pluginName := normalizePluginName(rawName)
 
 	cfg, err := LoadRegistryConfig(*cfgPath)
 	if err != nil {
@@ -164,13 +165,13 @@ func runPluginInstall(args []string) error {
 
 	// Update .wfctl.yaml lockfile if name@version was provided.
 	if _, ver := parseNameVersion(nameArg); ver != "" {
-		pluginName = normalizePluginName(pluginName)
-		binaryChecksum := ""
+		// Hash the installed binary (not the archive) so verifyInstalledChecksum matches.
 		binaryPath := filepath.Join(pluginDirVal, pluginName, pluginName)
-		if cs, hashErr := hashFileSHA256(binaryPath); hashErr == nil {
-			binaryChecksum = cs
+		sha, hashErr := hashFileSHA256(binaryPath)
+		if hashErr != nil {
+			fmt.Fprintf(os.Stderr, "warning: could not hash installed binary: %v\n", hashErr)
 		}
-		updateLockfileWithChecksum(pluginName, manifest.Version, manifest.Repository, sourceName, binaryChecksum)
+		updateLockfileWithChecksum(pluginName, manifest.Version, manifest.Repository, sourceName, sha)
 	}
 
 	return nil
@@ -515,34 +516,26 @@ func installFromURL(url, pluginDir string) error {
 	}
 
 	if err := ensurePluginBinary(destDir, pluginName); err != nil {
-		return fmt.Errorf("could not normalize binary name: %w", err)
+		return fmt.Errorf("normalize binary name: %w", err)
 	}
 
 	// Validate the installed plugin (same checks as registry installs).
 	if verifyErr := verifyInstalledPlugin(destDir, pluginName); verifyErr != nil {
 		return fmt.Errorf("post-install verification failed: %w", verifyErr)
 	}
 
-	binaryChecksum, hashErr := hashFileSHA256(filepath.Join(destDir, pluginName))
+	// Hash the installed binary (not the archive) so that verifyInstalledChecksum matches.
+	binaryPath := filepath.Join(destDir, pluginName)
+	checksum, hashErr := hashFileSHA256(binaryPath)
 	if hashErr != nil {
-		fmt.Fprintf(os.Stderr, "warning: could not compute binary checksum: %v\n", hashErr)
+		return fmt.Errorf("hash installed binary for lockfile: %w", hashErr)
 	}
-	updateLockfileWithChecksum(pluginName, pj.Version, pj.Repository, "", binaryChecksum)
+	updateLockfileWithChecksum(pluginName, pj.Version, pj.Repository, "", checksum)
 
 	fmt.Printf("Installed %s v%s to %s\n", pluginName, pj.Version, destDir)
 	return nil
 }
 
-// hashFileSHA256 computes the SHA-256 hex digest of the file at path.
-func hashFileSHA256(path string) (string, error) {
-	data, err := os.ReadFile(path)
-	if err != nil {
-		return "", fmt.Errorf("hash file %s: %w", path, err)
-	}
-	h := sha256.Sum256(data)
-	return hex.EncodeToString(h[:]), nil
-}
-
 // verifyInstalledChecksum reads the plugin binary and verifies its SHA-256 checksum.
 func verifyInstalledChecksum(pluginDir, pluginName, expectedSHA256 string) error {
 	binaryPath := filepath.Join(pluginDir, pluginName)
@@ -597,11 +590,13 @@ func installFromLocal(srcDir, pluginDir string) error {
 		return err
 	}
 
-	binaryChecksum, hashErr := hashFileSHA256(filepath.Join(destDir, pluginName))
+	// Update lockfile with binary checksum for consistency with other install paths.
+	installedBinary := filepath.Join(destDir, pluginName)
+	sha, hashErr := hashFileSHA256(installedBinary)
 	if hashErr != nil {
-		fmt.Fprintf(os.Stderr, "warning: could not compute binary checksum: %v\n", hashErr)
+		fmt.Fprintf(os.Stderr, "warning: could not hash installed binary: %v\n", hashErr)
 	}
-	updateLockfileWithChecksum(pluginName, pj.Version, "", "", binaryChecksum)
+	updateLockfileWithChecksum(pluginName, pj.Version, "", "", sha)
 
 	fmt.Printf("Installed %s v%s from %s to %s\n", pluginName, pj.Version, srcDir, destDir)
 	return nil
@@ -698,6 +693,16 @@ func parseGitHubRepoURL(repoURL string) (owner, repo string, err error) {
 	return parts[1], repoName, nil
 }
 
+// hashFileSHA256 returns the hex-encoded SHA-256 hash of the file at path.
+func hashFileSHA256(path string) (string, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return "", fmt.Errorf("hash file %s: %w", path, err)
+	}
+	h := sha256.Sum256(data)
+	return hex.EncodeToString(h[:]), nil
+}
+
 // extractTarGz decompresses and extracts a .tar.gz archive into destDir.
 // It guards against path traversal (zip-slip) attacks.
 func extractTarGz(data []byte, destDir string) error {

cmd/wfctl/plugin_install_new_test.go

@@ -60,6 +60,7 @@ func TestInstallFromURL(t *testing.T) {
 	pjContent := minimalPluginJSON(pluginName, "1.2.3")
 
 	tarball := buildPluginTarGz(t, pluginName, binaryContent, pjContent)
+	// The lockfile records the SHA-256 of the installed binary, not the archive.
 	binaryChecksum := sha256Hex(binaryContent)
 
 	// Serve tarball from a local httptest server.
@@ -115,7 +116,7 @@ func TestInstallFromURL(t *testing.T) {
 		t.Fatalf("lockfile missing entry for %q; entries: %v", pluginName, lf.Plugins)
 	}
 	if entry.SHA256 != binaryChecksum {
-		t.Errorf("lockfile checksum: got %q, want %q", entry.SHA256, binaryChecksum)
+		t.Errorf("lockfile checksum: got %q, want %q (should be binary hash, not archive hash)", entry.SHA256, binaryChecksum)
 	}
 	if entry.Version != "1.2.3" {
 		t.Errorf("lockfile version: got %q, want %q", entry.Version, "1.2.3")
@@ -432,8 +433,8 @@ func TestCopyFile(t *testing.T) {
 	if err != nil {
 		t.Fatalf("stat dest: %v", err)
 	}
-	if info.Mode() != wantMode {
-		t.Errorf("mode: got %v, want %v", info.Mode(), wantMode)
+	if info.Mode().Perm()&wantMode != wantMode {
+		t.Errorf("mode: got %v, want at least %v", info.Mode().Perm(), wantMode)
 	}
 }
 

cmd/wfctl/plugin_lockfile.go

@@ -90,10 +90,8 @@ func installFromLockfile(pluginDir, cfgPath string) error {
 		if entry.SHA256 != "" {
 			pluginInstallDir := filepath.Join(pluginDir, name)
 			if verifyErr := verifyInstalledChecksum(pluginInstallDir, name, entry.SHA256); verifyErr != nil {
-				fmt.Fprintf(os.Stderr, "CHECKSUM MISMATCH for %s: %v\n", name, verifyErr)
-				if removeErr := os.RemoveAll(pluginInstallDir); removeErr != nil {
-					fmt.Fprintf(os.Stderr, "warning: could not remove plugin dir: %v\n", removeErr)
-				}
+				fmt.Fprintf(os.Stderr, "CHECKSUM MISMATCH for %s: %v — removing plugin\n", name, verifyErr)
+				_ = os.RemoveAll(pluginInstallDir)
 				failed = append(failed, name)
 				continue
 			}
@@ -106,6 +104,7 @@ func installFromLockfile(pluginDir, cfgPath string) error {
 }
 
 // updateLockfileWithChecksum adds or updates a plugin entry in .wfctl.yaml with SHA-256 checksum.
+// The sha256Hash must be the hash of the installed binary, not the download archive.
 // Silently no-ops if the lockfile cannot be read or written (install still succeeds).
 func updateLockfileWithChecksum(pluginName, version, repository, registry, sha256Hash string) {
 	lf, err := loadPluginLockfile(wfctlYAMLPath)
@@ -118,8 +117,8 @@ func updateLockfileWithChecksum(pluginName, version, repository, registry, sha25
 	lf.Plugins[pluginName] = PluginLockEntry{
 		Version:    version,
 		Repository: repository,
-		SHA256:     sha256Hash,
 		Registry:   registry,
+		SHA256:     sha256Hash,
 	}
 	_ = lf.Save(wfctlYAMLPath)
 }

cmd/wfctl/registry_source.go

@@ -149,9 +149,10 @@ type StaticRegistrySource struct {
 }
 
 // NewStaticRegistrySource creates a new static-URL-backed registry source.
+// Returns an error if the URL is empty.
 func NewStaticRegistrySource(cfg RegistrySourceConfig) (*StaticRegistrySource, error) {
 	if cfg.URL == "" {
-		return nil, fmt.Errorf("static registry %q requires a URL", cfg.Name)
+		return nil, fmt.Errorf("registry %q: url is required for type=static", cfg.Name)
 	}
 	return &StaticRegistrySource{name: cfg.Name, baseURL: strings.TrimSuffix(cfg.URL, "/"), token: cfg.Token}, nil
 }
@@ -204,13 +205,8 @@ func (s *StaticRegistrySource) SearchPlugins(query string) ([]PluginSearchResult
 			strings.Contains(strings.ToLower(e.Name), q) ||
 			strings.Contains(strings.ToLower(e.Description), q) {
 			results = append(results, PluginSearchResult{
-				PluginSummary: PluginSummary{ //nolint:staticcheck // S1016: explicit fields for clarity across struct tag boundaries
-					Name:        e.Name,
-					Version:     e.Version,
-					Description: e.Description,
-					Tier:        e.Tier,
-				},
-				Source: s.name,
+				PluginSummary: PluginSummary(e),
+				Source:        s.name,
 			})
 		}
 	}

cmd/wfctl/registry_source_test.go

@@ -73,6 +73,17 @@ type errSentinel string
 
 func (e errSentinel) Error() string { return string(e) }
 
+// mustNewStaticRegistrySource is a test helper that calls NewStaticRegistrySource
+// and fails the test if an error is returned.
+func mustNewStaticRegistrySource(t *testing.T, cfg RegistrySourceConfig) *StaticRegistrySource {
+	t.Helper()
+	src, err := NewStaticRegistrySource(cfg)
+	if err != nil {
+		t.Fatalf("NewStaticRegistrySource: %v", err)
+	}
+	return src
+}
+
 // ---------------------------------------------------------------------------
 
 // TestStaticRegistrySource_FetchManifest verifies that FetchManifest fetches
@@ -93,7 +104,7 @@ func TestStaticRegistrySource_FetchManifest(t *testing.T) {
 	srv := buildStaticRegistryServer(t, nil, manifests)
 	defer srv.Close()
 
-	src, _ := NewStaticRegistrySource(RegistrySourceConfig{
+	src := mustNewStaticRegistrySource(t, RegistrySourceConfig{
 		Name: "test-static",
 		URL:  srv.URL,
 	})
@@ -116,7 +127,7 @@ func TestStaticRegistrySource_FetchManifest_NotFound(t *testing.T) {
 	srv := buildStaticRegistryServer(t, nil, map[string]*RegistryManifest{})
 	defer srv.Close()
 
-	src, _ := NewStaticRegistrySource(RegistrySourceConfig{
+	src := mustNewStaticRegistrySource(t, RegistrySourceConfig{
 		Name: "test-static",
 		URL:  srv.URL,
 	})
@@ -139,7 +150,7 @@ func TestStaticRegistrySource_ListPlugins(t *testing.T) {
 	srv := buildStaticRegistryServer(t, index, nil)
 	defer srv.Close()
 
-	src, _ := NewStaticRegistrySource(RegistrySourceConfig{
+	src := mustNewStaticRegistrySource(t, RegistrySourceConfig{
 		Name: "test-static",
 		URL:  srv.URL,
 	})
@@ -174,7 +185,7 @@ func TestStaticRegistrySource_SearchPlugins_AllWithEmptyQuery(t *testing.T) {
 	srv := buildStaticRegistryServer(t, index, nil)
 	defer srv.Close()
 
-	src, _ := NewStaticRegistrySource(RegistrySourceConfig{
+	src := mustNewStaticRegistrySource(t, RegistrySourceConfig{
 		Name: "test-static",
 		URL:  srv.URL,
 	})
@@ -200,7 +211,7 @@ func TestStaticRegistrySource_SearchPlugins_Filtering(t *testing.T) {
 	srv := buildStaticRegistryServer(t, index, nil)
 	defer srv.Close()
 
-	src, _ := NewStaticRegistrySource(RegistrySourceConfig{
+	src := mustNewStaticRegistrySource(t, RegistrySourceConfig{
 		Name: "test-static",
 		URL:  srv.URL,
 	})
@@ -256,7 +267,7 @@ func TestStaticRegistrySource_SearchPlugins_SourceName(t *testing.T) {
 	defer srv.Close()
 
 	const registryName = "my-static-registry"
-	src, _ := NewStaticRegistrySource(RegistrySourceConfig{
+	src := mustNewStaticRegistrySource(t, RegistrySourceConfig{
 		Name: registryName,
 		URL:  srv.URL,
 	})
@@ -284,7 +295,7 @@ func TestStaticRegistrySource_TrailingSlashStripped(t *testing.T) {
 	defer srv.Close()
 
 	// Pass URL with trailing slash.
-	src, _ := NewStaticRegistrySource(RegistrySourceConfig{
+	src := mustNewStaticRegistrySource(t, RegistrySourceConfig{
 		Name: "test",
 		URL:  srv.URL + "/",
 	})
@@ -300,11 +311,23 @@ func TestStaticRegistrySource_TrailingSlashStripped(t *testing.T) {
 
 // TestStaticRegistrySource_Name verifies that the registry name is returned correctly.
 func TestStaticRegistrySource_Name(t *testing.T) {
-	src, _ := NewStaticRegistrySource(RegistrySourceConfig{
+	src := mustNewStaticRegistrySource(t, RegistrySourceConfig{
 		Name: "my-registry",
 		URL:  "https://example.com",
 	})
 	if src.Name() != "my-registry" {
 		t.Errorf("Name: got %q, want %q", src.Name(), "my-registry")
 	}
 }
+
+// TestStaticRegistrySource_EmptyURL verifies that NewStaticRegistrySource returns
+// an error when the URL is empty.
+func TestStaticRegistrySource_EmptyURL(t *testing.T) {
+	_, err := NewStaticRegistrySource(RegistrySourceConfig{
+		Name: "no-url-registry",
+		URL:  "",
+	})
+	if err == nil {
+		t.Fatal("expected error for empty URL, got nil")
+	}
+}