feat(cli): define plugin objects and basic plugin listing ability

cli/Makefile

@@ -1,11 +1,14 @@
 BINARY_NAME := ossie
 BUILD_DIR   := dist
 
-.PHONY: build test lint release-dry-run clean
+.PHONY: build install test lint release-dry-run clean
 
 build:
 	go build -o $(BUILD_DIR)/$(BINARY_NAME) .
 
+install:
+	go build -o $(shell go env GOPATH)/bin/$(BINARY_NAME) .
+
 test:
 	go test ./...
 

cli/cmd/plugin/list.go

@@ -2,17 +2,46 @@ package plugin
 
 import (
 	"fmt"
+	"os"
+	"path/filepath"
+	"text/tabwriter"
 
 	"github.com/spf13/cobra"
+
+	"github.com/apache/ossie/cli/internal/ossiedir"
+	"github.com/apache/ossie/cli/internal/plugin"
 )
 
 var listCmd = &cobra.Command{
 	Use:   "list",
-	Short: "List installed and available plugins",
-	RunE:  runPluginList,
+	Short: "List installed plugins",
+	// TODO(P1): cross-reference against the embedded plugin registry to show
+	// latest available versions and update indicators once registry embedding
+	// (F4) is implemented.
+	RunE: runPluginList,
 }
 
 func runPluginList(cmd *cobra.Command, args []string) error {
-	fmt.Fprintln(cmd.OutOrStdout(), "not yet implemented")
-	return nil
+	pluginsDir, err := ossiedir.PluginDir()
+	if err != nil {
+		return err
+	}
+
+	plugins, err := plugin.Discover(pluginsDir, os.Stderr)
+	if err != nil {
+		return err
+	}
+
+	if len(plugins) == 0 {
+		fmt.Fprintln(cmd.OutOrStdout(), "no plugins installed")
+		return nil
+	}
+
+	w := tabwriter.NewWriter(cmd.OutOrStdout(), 0, 0, 2, ' ', 0)
+	fmt.Fprintln(w, "NAME\tPLATFORM\tSPEC")
+	for _, p := range plugins {
+		name := filepath.Base(p.Path)
+		fmt.Fprintf(w, "%s\t%s\t%s\n", name, p.Platform.Name, p.OSSIEPluginSpec)
+	}
+	return w.Flush()
 }

cli/go.mod

@@ -2,7 +2,10 @@ module github.com/apache/ossie/cli
 
 go 1.26.2
 
-require github.com/spf13/cobra v1.10.2
+require (
+	github.com/spf13/cobra v1.10.2
+	gopkg.in/yaml.v3 v3.0.1
+)
 
 require (
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect

cli/go.sum

@@ -7,4 +7,7 @@ github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiT
 github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
 github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

cli/internal/plugin/discover.go

@@ -0,0 +1,76 @@
+package plugin
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+
+	"gopkg.in/yaml.v3"
+)
+
+const pluginYAML = "plugin.yaml"
+
+// Discover scans pluginsDir for subdirectories that contain a plugin.yaml,
+// parses and validates each one, and returns all valid plugins.
+//
+// Malformed or invalid plugin directories are skipped with a warning written
+// to stderr in the format:
+//
+//	warning: skipping plugin at <path>: <reason>
+//
+// A non-existent pluginsDir is treated as empty and returns (nil, nil).
+// A hard error is only returned if pluginsDir itself cannot be read.
+func Discover(pluginsDir string, stderr io.Writer) ([]*Plugin, error) {
+	entries, err := os.ReadDir(pluginsDir)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return nil, nil
+		}
+		return nil, fmt.Errorf("could not read plugin directory %s: %w", pluginsDir, err)
+	}
+
+	var plugins []*Plugin
+	for _, entry := range entries {
+		// TODO: handle symlinked plugin directories
+		// (entry.Type()&os.ModeSymlink != 0 requires os.Stat to resolve)
+		if !entry.IsDir() {
+			continue
+		}
+		pluginPath := filepath.Join(pluginsDir, entry.Name())
+		p, err := loadPlugin(pluginPath)
+		if err != nil {
+			fmt.Fprintf(stderr, "warning: skipping plugin at %s: %s\n", pluginPath, err)
+			continue
+		}
+		plugins = append(plugins, p)
+	}
+	return plugins, nil
+}
+
+// loadPlugin reads, parses, and validates the plugin.yaml inside dir.
+func loadPlugin(dir string) (*Plugin, error) {
+	yamlPath := filepath.Join(dir, pluginYAML)
+	data, err := os.ReadFile(yamlPath)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return nil, fmt.Errorf("no plugin.yaml found")
+		}
+		return nil, fmt.Errorf("could not read plugin.yaml: %w", err)
+	}
+
+	// yaml.Unmarshal is lenient by default: unknown fields are silently ignored.
+	// This is intentional — future spec versions may add fields that older CLI
+	// versions should tolerate rather than reject.
+	var raw rawPlugin
+	if err := yaml.Unmarshal(data, &raw); err != nil {
+		return nil, fmt.Errorf("invalid YAML: %w", err)
+	}
+
+	if err := raw.validate(); err != nil {
+		return nil, err
+	}
+
+	return raw.toPlugin(dir), nil
+}