From 3c88a83ef999891ec6beede66ca0c2e2b227890a Mon Sep 17 00:00:00 2001 From: Quigley Malcolm Date: Tue, 9 Jun 2026 16:12:29 -0500 Subject: [PATCH 01/22] feat(cli): scaffold go module with cobra command tree MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The OSI converters currently require manual environment setup and per-converter invocation. This lays the foundation for a unified CLI (osi) that will discover and invoke converters as plugins via a stdin/stdout JSON protocol. Creates cli/ at the repo root as a self-contained Go module (github.com/open-semantic-interchange/osi/cli). All commands are stubbed — no logic is wired in this commit. Design decisions: - Go chosen for static binary distribution; no runtime dependency for end users (brew/apt installable) - internal/osidir owns ~/.osi/plugins/ initialization and respects $OSI_PLUGIN_DIR for override; uses os.UserHomeDir() rather than $HOME for Windows portability - PersistentPreRunE on the root command ensures dir init runs before every subcommand; commented caveat that Cobra does not chain this automatically if a subcommand defines its own - MarkFlagsMutuallyExclusive("from", "to") handles the both-set case on osi convert; the neither-set case is validated manually in RunE since Cobra only guards against both being provided Build pipeline (Makefile, .goreleaser.yaml) and CI follow in separate commits. --- .gitignore | 4 ++++ cli/.tool-versions | 1 + cli/cmd/convert.go | 39 ++++++++++++++++++++++++++++++++++ cli/cmd/plugin/install.go | 22 +++++++++++++++++++ cli/cmd/plugin/list.go | 18 ++++++++++++++++ cli/cmd/plugin/plugin.go | 16 ++++++++++++++ cli/cmd/plugin/remove.go | 19 +++++++++++++++++ cli/cmd/root.go | 38 +++++++++++++++++++++++++++++++++ cli/cmd/validate.go | 24 +++++++++++++++++++++ cli/go.mod | 10 +++++++++ cli/go.sum | 10 +++++++++ cli/internal/osidir/osidir.go | 40 +++++++++++++++++++++++++++++++++++ cli/main.go | 21 ++++++++++++++++++ 13 files changed, 262 insertions(+) create mode 100644 cli/.tool-versions create mode 100644 cli/cmd/convert.go create mode 100644 cli/cmd/plugin/install.go create mode 100644 cli/cmd/plugin/list.go create mode 100644 cli/cmd/plugin/plugin.go create mode 100644 cli/cmd/plugin/remove.go create mode 100644 cli/cmd/root.go create mode 100644 cli/cmd/validate.go create mode 100644 cli/go.mod create mode 100644 cli/go.sum create mode 100644 cli/internal/osidir/osidir.go create mode 100644 cli/main.go diff --git a/.gitignore b/.gitignore index 63e36ff..8cf6aa8 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,6 @@ **/__pycache__/ **/.venv/ + +# Go CLI +cli/dist/ +cli/osi diff --git a/cli/.tool-versions b/cli/.tool-versions new file mode 100644 index 0000000..05a23a6 --- /dev/null +++ b/cli/.tool-versions @@ -0,0 +1 @@ +golang 1.26.2 diff --git a/cli/cmd/convert.go b/cli/cmd/convert.go new file mode 100644 index 0000000..aa8797d --- /dev/null +++ b/cli/cmd/convert.go @@ -0,0 +1,39 @@ +package cmd + +import ( + "fmt" + + "github.com/spf13/cobra" +) + +var convertCmd = &cobra.Command{ + Use: "convert --from --input | --to --input ", + Short: "Convert a semantic model between OSI and a platform format", + RunE: runConvert, +} + +func init() { + convertCmd.Flags().String("from", "", "Source platform — converts platform → OSI") + convertCmd.Flags().String("to", "", "Target platform — converts OSI → platform") + convertCmd.Flags().StringP("input", "i", "", "Input file or directory path (required)") + convertCmd.Flags().StringP("output", "o", "", "Output directory path (default: ./osi-output//)") + convertCmd.Flags().String("plugin", "", "Path to plugin directory (bypasses name-based discovery)") + convertCmd.Flags().Int("timeout", 60, "Plugin invocation timeout in seconds") + convertCmd.Flags().String("max-input-size", "100MB", "Maximum total input size (e.g. 500MB)") + + _ = convertCmd.MarkFlagRequired("input") + convertCmd.MarkFlagsMutuallyExclusive("from", "to") +} + +func runConvert(cmd *cobra.Command, args []string) error { + from, _ := cmd.Flags().GetString("from") + to, _ := cmd.Flags().GetString("to") + + // MarkFlagsMutuallyExclusive handles the both-set case; handle neither here. + if from == "" && to == "" { + return fmt.Errorf("exactly one of --from or --to must be specified") + } + + fmt.Fprintln(cmd.OutOrStdout(), "not yet implemented") + return nil +} diff --git a/cli/cmd/plugin/install.go b/cli/cmd/plugin/install.go new file mode 100644 index 0000000..aabde2d --- /dev/null +++ b/cli/cmd/plugin/install.go @@ -0,0 +1,22 @@ +package plugin + +import ( + "fmt" + + "github.com/spf13/cobra" +) + +var installCmd = &cobra.Command{ + Use: "install [name[@version] | url]", + Short: "Install a plugin from the registry or a URL", + RunE: runPluginInstall, +} + +func init() { + installCmd.Flags().Bool("all", false, "Install the latest version of all registry plugins") +} + +func runPluginInstall(cmd *cobra.Command, args []string) error { + fmt.Fprintln(cmd.OutOrStdout(), "not yet implemented") + return nil +} diff --git a/cli/cmd/plugin/list.go b/cli/cmd/plugin/list.go new file mode 100644 index 0000000..f69e8bb --- /dev/null +++ b/cli/cmd/plugin/list.go @@ -0,0 +1,18 @@ +package plugin + +import ( + "fmt" + + "github.com/spf13/cobra" +) + +var listCmd = &cobra.Command{ + Use: "list", + Short: "List installed and available plugins", + RunE: runPluginList, +} + +func runPluginList(cmd *cobra.Command, args []string) error { + fmt.Fprintln(cmd.OutOrStdout(), "not yet implemented") + return nil +} diff --git a/cli/cmd/plugin/plugin.go b/cli/cmd/plugin/plugin.go new file mode 100644 index 0000000..a57e103 --- /dev/null +++ b/cli/cmd/plugin/plugin.go @@ -0,0 +1,16 @@ +package plugin + +import "github.com/spf13/cobra" + +// Cmd is the parent "osi plugin" command. It is exported so cmd/root.go can +// register it. Invoking it bare prints help. +var Cmd = &cobra.Command{ + Use: "plugin", + Short: "Manage OSI plugins", +} + +func init() { + Cmd.AddCommand(listCmd) + Cmd.AddCommand(installCmd) + Cmd.AddCommand(removeCmd) +} diff --git a/cli/cmd/plugin/remove.go b/cli/cmd/plugin/remove.go new file mode 100644 index 0000000..1b88669 --- /dev/null +++ b/cli/cmd/plugin/remove.go @@ -0,0 +1,19 @@ +package plugin + +import ( + "fmt" + + "github.com/spf13/cobra" +) + +var removeCmd = &cobra.Command{ + Use: "remove ", + Short: "Remove an installed plugin", + Args: cobra.ExactArgs(1), + RunE: runPluginRemove, +} + +func runPluginRemove(cmd *cobra.Command, args []string) error { + fmt.Fprintln(cmd.OutOrStdout(), "not yet implemented") + return nil +} diff --git a/cli/cmd/root.go b/cli/cmd/root.go new file mode 100644 index 0000000..40d1fbc --- /dev/null +++ b/cli/cmd/root.go @@ -0,0 +1,38 @@ +package cmd + +import ( + "github.com/open-semantic-interchange/osi/cli/cmd/plugin" + "github.com/open-semantic-interchange/osi/cli/internal/osidir" + "github.com/spf13/cobra" +) + +var rootCmd = &cobra.Command{ + Use: "osi", + Short: "Open Semantic Interchange CLI", + Long: `osi is the command-line tool for the Open Semantic Interchange (OSI) project.`, + // NOTE: Cobra does NOT automatically chain PersistentPreRunE from parent to + // child. If any subcommand defines its own PersistentPreRunE or PreRunE, this + // function will not run for that subcommand. Future subcommands that define + // their own must call osidir.EnsurePluginDir() explicitly. + PersistentPreRunE: func(cmd *cobra.Command, args []string) error { + return osidir.EnsurePluginDir() + }, +} + +// Execute runs the root command. Called by main. +func Execute() error { + return rootCmd.Execute() +} + +// SetVersion sets the version string reported by `osi --version`. +func SetVersion(v string) { + rootCmd.Version = v +} + +func init() { + rootCmd.PersistentFlags().BoolP("verbose", "v", false, "Enable verbose output (shows plugin stderr)") + + rootCmd.AddCommand(convertCmd) + rootCmd.AddCommand(validateCmd) + rootCmd.AddCommand(plugin.Cmd) +} diff --git a/cli/cmd/validate.go b/cli/cmd/validate.go new file mode 100644 index 0000000..5ef9edc --- /dev/null +++ b/cli/cmd/validate.go @@ -0,0 +1,24 @@ +package cmd + +import ( + "fmt" + + "github.com/spf13/cobra" +) + +var validateCmd = &cobra.Command{ + Use: "validate [flags] [...]", + Short: "Validate one or more OSI YAML or JSON files", + Args: cobra.MinimumNArgs(1), + RunE: runValidate, +} + +func init() { + validateCmd.Flags().Bool("strict", false, "Promote warnings to errors") + validateCmd.Flags().String("output", "text", "Output format: text or json") +} + +func runValidate(cmd *cobra.Command, args []string) error { + fmt.Fprintln(cmd.OutOrStdout(), "not yet implemented") + return nil +} diff --git a/cli/go.mod b/cli/go.mod new file mode 100644 index 0000000..eabd4e0 --- /dev/null +++ b/cli/go.mod @@ -0,0 +1,10 @@ +module github.com/open-semantic-interchange/osi/cli + +go 1.22 + +require github.com/spf13/cobra v1.10.2 + +require ( + github.com/inconshreveable/mousetrap v1.1.0 // indirect + github.com/spf13/pflag v1.0.9 // indirect +) diff --git a/cli/go.sum b/cli/go.sum new file mode 100644 index 0000000..a6ee3e0 --- /dev/null +++ b/cli/go.sum @@ -0,0 +1,10 @@ +github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g= +github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8= +github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= +github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= +github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU= +github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4= +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/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= diff --git a/cli/internal/osidir/osidir.go b/cli/internal/osidir/osidir.go new file mode 100644 index 0000000..cdb3f6b --- /dev/null +++ b/cli/internal/osidir/osidir.go @@ -0,0 +1,40 @@ +package osidir + +import ( + "fmt" + "os" + "path/filepath" +) + +const ( + defaultOSIDir = ".osi" + pluginsSubdir = "plugins" + envVar = "OSI_PLUGIN_DIR" +) + +// PluginDir returns the resolved plugin directory path. +// It respects $OSI_PLUGIN_DIR if set, otherwise defaults to ~/.osi/plugins/. +func PluginDir() (string, error) { + if override := os.Getenv(envVar); override != "" { + return override, nil + } + // Use os.UserHomeDir rather than $HOME for Windows portability. + home, err := os.UserHomeDir() + if err != nil { + return "", fmt.Errorf("could not determine home directory: %w", err) + } + return filepath.Join(home, defaultOSIDir, pluginsSubdir), nil +} + +// EnsurePluginDir ensures the plugin directory exists, creating it if needed. +// It is safe to call multiple times — os.MkdirAll is idempotent. +func EnsurePluginDir() error { + dir, err := PluginDir() + if err != nil { + return err + } + if err := os.MkdirAll(dir, 0755); err != nil { + return fmt.Errorf("could not create plugin directory %s: %w", dir, err) + } + return nil +} diff --git a/cli/main.go b/cli/main.go new file mode 100644 index 0000000..9262cb5 --- /dev/null +++ b/cli/main.go @@ -0,0 +1,21 @@ +package main + +import ( + "os" + + "github.com/open-semantic-interchange/osi/cli/cmd" +) + +// version, commit, and date are set at build time by GoReleaser via ldflags. +var ( + version = "dev" + commit = "none" + date = "unknown" +) + +func main() { + cmd.SetVersion(version) + if err := cmd.Execute(); err != nil { + os.Exit(1) + } +} From fcefdc89f9cde720af3bdfbe48ef4a45b9be1491 Mon Sep 17 00:00:00 2001 From: Quigley Malcolm Date: Tue, 9 Jun 2026 16:33:56 -0500 Subject: [PATCH 02/22] chore(cli): add makefile and goreleaser build pipeline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Enables local builds and cross-platform release artifacts for the OSI CLI. Makefile provides standard targets for day-to-day development: build, test, lint, release-dry-run, and clean. All targets are designed to run from within cli/. GoReleaser config targets linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, and windows/amd64. windows/arm64 is excluded — no widely available CI runner and negligible current demand. CGO_ENABLED=0 is set for fully static binaries, enabling cross-compilation from any host without a C toolchain. Version, commit, and date are injected at build time via ldflags from the vars declared in main.go. --- cli/.goreleaser.yaml | 48 ++++++++++++++++++++++++++++++++++++++++++++ cli/Makefile | 19 ++++++++++++++++++ 2 files changed, 67 insertions(+) create mode 100644 cli/.goreleaser.yaml create mode 100644 cli/Makefile diff --git a/cli/.goreleaser.yaml b/cli/.goreleaser.yaml new file mode 100644 index 0000000..2351e42 --- /dev/null +++ b/cli/.goreleaser.yaml @@ -0,0 +1,48 @@ +version: 2 + +project_name: osi + +before: + hooks: + - go mod tidy + +builds: + - id: osi + main: . + binary: osi + goos: + - linux + - darwin + - windows + goarch: + - amd64 + - arm64 + ignore: + - goos: windows + goarch: arm64 + env: + - CGO_ENABLED=0 + ldflags: + - -s -w + - -X main.version={{.Version}} + - -X main.commit={{.Commit}} + - -X main.date={{.Date}} + +archives: + - id: osi + format: tar.gz + format_overrides: + - goos: windows + format: zip + name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}" + +checksum: + name_template: "checksums.txt" + +changelog: + sort: asc + filters: + exclude: + - "^docs:" + - "^test:" + - "^chore:" diff --git a/cli/Makefile b/cli/Makefile new file mode 100644 index 0000000..ed8de03 --- /dev/null +++ b/cli/Makefile @@ -0,0 +1,19 @@ +BINARY_NAME := osi +BUILD_DIR := dist + +.PHONY: build test lint release-dry-run clean + +build: + go build -o $(BUILD_DIR)/$(BINARY_NAME) . + +test: + go test ./... + +lint: + go vet ./... + +release-dry-run: + goreleaser release --snapshot --clean --config .goreleaser.yaml + +clean: + rm -rf $(BUILD_DIR) From ac660a089fc1550beff308c353c0f4ff767ebbca Mon Sep 17 00:00:00 2001 From: Quigley Malcolm Date: Tue, 9 Jun 2026 16:40:00 -0500 Subject: [PATCH 03/22] ci(cli): add github actions workflow for build and test MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Runs go build, go vet, and go test on every push and pull request that touches cli/ or the workflow file itself. The paths filter prevents CLI changes from triggering unrelated workflows in this polyglot repo and vice versa. Go version is derived from go-version-file: cli/go.mod so the workflow automatically picks up any future toolchain bumps without a separate workflow edit. defaults.run.working-directory avoids repeating cd cli/ on every step. Cross-platform build testing is not included — CGO_ENABLED=0 means the linux/amd64 build is representative of all targets. GoReleaser snapshot builds are deferred to a future release workflow. --- .github/workflows/cli-ci.yml | 38 ++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 .github/workflows/cli-ci.yml diff --git a/.github/workflows/cli-ci.yml b/.github/workflows/cli-ci.yml new file mode 100644 index 0000000..e729089 --- /dev/null +++ b/.github/workflows/cli-ci.yml @@ -0,0 +1,38 @@ +name: CLI CI + +on: + push: + paths: + - 'cli/**' + - '.github/workflows/cli-ci.yml' + pull_request: + paths: + - 'cli/**' + - '.github/workflows/cli-ci.yml' + +jobs: + build-and-test: + name: Build and test + runs-on: ubuntu-latest + defaults: + run: + working-directory: cli + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Go + uses: actions/setup-go@v5 + with: + go-version-file: cli/go.mod + cache-dependency-path: cli/go.sum + + - name: go build + run: go build ./... + + - name: go vet + run: go vet ./... + + - name: go test + run: go test ./... From 5f269d2c28390085a49b8affcf593051bbca5b86 Mon Sep 17 00:00:00 2001 From: Quigley Malcolm Date: Tue, 9 Jun 2026 17:47:45 -0500 Subject: [PATCH 04/22] test(cli): add unit tests for internal/osidir Covers the only logic in F1 that warrants testing: $OSI_PLUGIN_DIR env var override, default path construction via os.UserHomeDir(), directory creation, and idempotent re-invocation of EnsurePluginDir. t.Setenv is used throughout so env var mutations are automatically restored after each test. t.TempDir is used for filesystem tests so no cleanup is needed and tests are safe to run in parallel. --- cli/internal/osidir/osidir_test.go | 65 ++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 cli/internal/osidir/osidir_test.go diff --git a/cli/internal/osidir/osidir_test.go b/cli/internal/osidir/osidir_test.go new file mode 100644 index 0000000..1d39193 --- /dev/null +++ b/cli/internal/osidir/osidir_test.go @@ -0,0 +1,65 @@ +package osidir + +import ( + "os" + "path/filepath" + "testing" +) + +func TestPluginDir_envOverride(t *testing.T) { + want := "/custom/plugin/dir" + t.Setenv(envVar, want) + + got, err := PluginDir() + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if got != want { + t.Errorf("got %q, want %q", got, want) + } +} + +func TestPluginDir_default(t *testing.T) { + t.Setenv(envVar, "") + + home, err := os.UserHomeDir() + if err != nil { + t.Fatalf("could not determine home dir: %v", err) + } + want := filepath.Join(home, defaultOSIDir, pluginsSubdir) + + got, err := PluginDir() + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if got != want { + t.Errorf("got %q, want %q", got, want) + } +} + +func TestEnsurePluginDir_createsDirectory(t *testing.T) { + tmp := t.TempDir() + target := filepath.Join(tmp, "plugins") + t.Setenv(envVar, target) + + if err := EnsurePluginDir(); err != nil { + t.Fatalf("unexpected error: %v", err) + } + + if _, err := os.Stat(target); os.IsNotExist(err) { + t.Errorf("expected directory %q to exist, but it does not", target) + } +} + +func TestEnsurePluginDir_idempotent(t *testing.T) { + tmp := t.TempDir() + target := filepath.Join(tmp, "plugins") + t.Setenv(envVar, target) + + if err := EnsurePluginDir(); err != nil { + t.Fatalf("first call failed: %v", err) + } + if err := EnsurePluginDir(); err != nil { + t.Fatalf("second call failed: %v", err) + } +} From 780dcdb43703b503ef94c6b16b108b8d10b98b96 Mon Sep 17 00:00:00 2001 From: Quigley Malcolm Date: Wed, 10 Jun 2026 15:45:12 -0500 Subject: [PATCH 05/22] chore(cli): rename osi to ossie throughout cli scaffold MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Project branding has changed from OSI to OSSIE. Updates all user-facing and internal references in the CLI: - Binary name: osi → ossie - Go module path: .../osi/cli → .../ossie/cli - Default plugin directory: ~/.osi → ~/.ossie - Environment variable: OSI_PLUGIN_DIR → OSSIE_PLUGIN_DIR - GoReleaser project name and archive ids - All command descriptions and flag help text - Output directory default: ./osi-output → ./ossie-output --- cli/.goreleaser.yaml | 8 ++++---- cli/Makefile | 2 +- cli/cmd/convert.go | 8 ++++---- cli/cmd/plugin/plugin.go | 4 ++-- cli/cmd/root.go | 10 +++++----- cli/cmd/validate.go | 2 +- cli/go.mod | 2 +- cli/internal/osidir/osidir.go | 6 +++--- cli/main.go | 2 +- 9 files changed, 22 insertions(+), 22 deletions(-) diff --git a/cli/.goreleaser.yaml b/cli/.goreleaser.yaml index 2351e42..3a0a17b 100644 --- a/cli/.goreleaser.yaml +++ b/cli/.goreleaser.yaml @@ -1,15 +1,15 @@ version: 2 -project_name: osi +project_name: ossie before: hooks: - go mod tidy builds: - - id: osi + - id: ossie main: . - binary: osi + binary: ossie goos: - linux - darwin @@ -29,7 +29,7 @@ builds: - -X main.date={{.Date}} archives: - - id: osi + - id: ossie format: tar.gz format_overrides: - goos: windows diff --git a/cli/Makefile b/cli/Makefile index ed8de03..9ecbcb7 100644 --- a/cli/Makefile +++ b/cli/Makefile @@ -1,4 +1,4 @@ -BINARY_NAME := osi +BINARY_NAME := ossie BUILD_DIR := dist .PHONY: build test lint release-dry-run clean diff --git a/cli/cmd/convert.go b/cli/cmd/convert.go index aa8797d..92722ee 100644 --- a/cli/cmd/convert.go +++ b/cli/cmd/convert.go @@ -8,15 +8,15 @@ import ( var convertCmd = &cobra.Command{ Use: "convert --from --input | --to --input ", - Short: "Convert a semantic model between OSI and a platform format", + Short: "Convert a semantic model between OSSIE and a platform format", RunE: runConvert, } func init() { - convertCmd.Flags().String("from", "", "Source platform — converts platform → OSI") - convertCmd.Flags().String("to", "", "Target platform — converts OSI → platform") + convertCmd.Flags().String("from", "", "Source platform — converts platform → OSSIE") + convertCmd.Flags().String("to", "", "Target platform — converts OSSIE → platform") convertCmd.Flags().StringP("input", "i", "", "Input file or directory path (required)") - convertCmd.Flags().StringP("output", "o", "", "Output directory path (default: ./osi-output//)") + convertCmd.Flags().StringP("output", "o", "", "Output directory path (default: ./ossie-output//)") convertCmd.Flags().String("plugin", "", "Path to plugin directory (bypasses name-based discovery)") convertCmd.Flags().Int("timeout", 60, "Plugin invocation timeout in seconds") convertCmd.Flags().String("max-input-size", "100MB", "Maximum total input size (e.g. 500MB)") diff --git a/cli/cmd/plugin/plugin.go b/cli/cmd/plugin/plugin.go index a57e103..d996f13 100644 --- a/cli/cmd/plugin/plugin.go +++ b/cli/cmd/plugin/plugin.go @@ -2,11 +2,11 @@ package plugin import "github.com/spf13/cobra" -// Cmd is the parent "osi plugin" command. It is exported so cmd/root.go can +// Cmd is the parent "ossie plugin" command. It is exported so cmd/root.go can // register it. Invoking it bare prints help. var Cmd = &cobra.Command{ Use: "plugin", - Short: "Manage OSI plugins", + Short: "Manage OSSIE plugins", } func init() { diff --git a/cli/cmd/root.go b/cli/cmd/root.go index 40d1fbc..45347bc 100644 --- a/cli/cmd/root.go +++ b/cli/cmd/root.go @@ -1,15 +1,15 @@ package cmd import ( - "github.com/open-semantic-interchange/osi/cli/cmd/plugin" - "github.com/open-semantic-interchange/osi/cli/internal/osidir" + "github.com/open-semantic-interchange/ossie/cli/cmd/plugin" + "github.com/open-semantic-interchange/ossie/cli/internal/osidir" "github.com/spf13/cobra" ) var rootCmd = &cobra.Command{ - Use: "osi", + Use: "ossie", Short: "Open Semantic Interchange CLI", - Long: `osi is the command-line tool for the Open Semantic Interchange (OSI) project.`, + Long: `ossie is the command-line tool for the Open Semantic Interchange (OSSIE) project.`, // NOTE: Cobra does NOT automatically chain PersistentPreRunE from parent to // child. If any subcommand defines its own PersistentPreRunE or PreRunE, this // function will not run for that subcommand. Future subcommands that define @@ -24,7 +24,7 @@ func Execute() error { return rootCmd.Execute() } -// SetVersion sets the version string reported by `osi --version`. +// SetVersion sets the version string reported by `ossie --version`. func SetVersion(v string) { rootCmd.Version = v } diff --git a/cli/cmd/validate.go b/cli/cmd/validate.go index 5ef9edc..b11d00a 100644 --- a/cli/cmd/validate.go +++ b/cli/cmd/validate.go @@ -8,7 +8,7 @@ import ( var validateCmd = &cobra.Command{ Use: "validate [flags] [...]", - Short: "Validate one or more OSI YAML or JSON files", + Short: "Validate one or more OSSIE YAML or JSON files", Args: cobra.MinimumNArgs(1), RunE: runValidate, } diff --git a/cli/go.mod b/cli/go.mod index eabd4e0..a828425 100644 --- a/cli/go.mod +++ b/cli/go.mod @@ -1,4 +1,4 @@ -module github.com/open-semantic-interchange/osi/cli +module github.com/open-semantic-interchange/ossie/cli go 1.22 diff --git a/cli/internal/osidir/osidir.go b/cli/internal/osidir/osidir.go index cdb3f6b..27fb742 100644 --- a/cli/internal/osidir/osidir.go +++ b/cli/internal/osidir/osidir.go @@ -7,13 +7,13 @@ import ( ) const ( - defaultOSIDir = ".osi" + defaultOSIDir = ".ossie" pluginsSubdir = "plugins" - envVar = "OSI_PLUGIN_DIR" + envVar = "OSSIE_PLUGIN_DIR" ) // PluginDir returns the resolved plugin directory path. -// It respects $OSI_PLUGIN_DIR if set, otherwise defaults to ~/.osi/plugins/. +// It respects $OSSIE_PLUGIN_DIR if set, otherwise defaults to ~/.ossie/plugins/. func PluginDir() (string, error) { if override := os.Getenv(envVar); override != "" { return override, nil diff --git a/cli/main.go b/cli/main.go index 9262cb5..9d2a202 100644 --- a/cli/main.go +++ b/cli/main.go @@ -3,7 +3,7 @@ package main import ( "os" - "github.com/open-semantic-interchange/osi/cli/cmd" + "github.com/open-semantic-interchange/ossie/cli/cmd" ) // version, commit, and date are set at build time by GoReleaser via ldflags. From 22e986e148d575bfa00585079242114ee1088386 Mon Sep 17 00:00:00 2001 From: Quigley Malcolm Date: Fri, 12 Jun 2026 10:04:42 -0500 Subject: [PATCH 06/22] chore(cli): rename internal osidir package to ossiedir MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Completes the OSI → OSSIE rename by updating the internal package directory, package declaration, and import reference in cmd/root.go. --- cli/cmd/root.go | 6 +++--- cli/internal/{osidir => ossiedir}/osidir.go | 2 +- cli/internal/{osidir => ossiedir}/osidir_test.go | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) rename cli/internal/{osidir => ossiedir}/osidir.go (98%) rename cli/internal/{osidir => ossiedir}/osidir_test.go (98%) diff --git a/cli/cmd/root.go b/cli/cmd/root.go index 45347bc..772d87b 100644 --- a/cli/cmd/root.go +++ b/cli/cmd/root.go @@ -2,7 +2,7 @@ package cmd import ( "github.com/open-semantic-interchange/ossie/cli/cmd/plugin" - "github.com/open-semantic-interchange/ossie/cli/internal/osidir" + "github.com/open-semantic-interchange/ossie/cli/internal/ossiedir" "github.com/spf13/cobra" ) @@ -13,9 +13,9 @@ var rootCmd = &cobra.Command{ // NOTE: Cobra does NOT automatically chain PersistentPreRunE from parent to // child. If any subcommand defines its own PersistentPreRunE or PreRunE, this // function will not run for that subcommand. Future subcommands that define - // their own must call osidir.EnsurePluginDir() explicitly. + // their own must call ossiedir.EnsurePluginDir() explicitly. PersistentPreRunE: func(cmd *cobra.Command, args []string) error { - return osidir.EnsurePluginDir() + return ossiedir.EnsurePluginDir() }, } diff --git a/cli/internal/osidir/osidir.go b/cli/internal/ossiedir/osidir.go similarity index 98% rename from cli/internal/osidir/osidir.go rename to cli/internal/ossiedir/osidir.go index 27fb742..9396041 100644 --- a/cli/internal/osidir/osidir.go +++ b/cli/internal/ossiedir/osidir.go @@ -1,4 +1,4 @@ -package osidir +package ossiedir import ( "fmt" diff --git a/cli/internal/osidir/osidir_test.go b/cli/internal/ossiedir/osidir_test.go similarity index 98% rename from cli/internal/osidir/osidir_test.go rename to cli/internal/ossiedir/osidir_test.go index 1d39193..0fe341c 100644 --- a/cli/internal/osidir/osidir_test.go +++ b/cli/internal/ossiedir/osidir_test.go @@ -1,4 +1,4 @@ -package osidir +package ossiedir import ( "os" From 32955eb43e302fc25c2c46f486d8762d21ceeaf8 Mon Sep 17 00:00:00 2001 From: Quigley Malcolm Date: Tue, 23 Jun 2026 15:32:53 -0500 Subject: [PATCH 07/22] fix(ossiedir): rename defaultOSIDir constant to defaultOssieDir MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The osi → ossie rename missed this unexported constant. The value (.ossie) was already correct; only the identifier name was stale. --- cli/internal/ossiedir/osidir.go | 4 ++-- cli/internal/ossiedir/osidir_test.go | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/cli/internal/ossiedir/osidir.go b/cli/internal/ossiedir/osidir.go index 9396041..051a8bd 100644 --- a/cli/internal/ossiedir/osidir.go +++ b/cli/internal/ossiedir/osidir.go @@ -7,7 +7,7 @@ import ( ) const ( - defaultOSIDir = ".ossie" + defaultOssieDir = ".ossie" pluginsSubdir = "plugins" envVar = "OSSIE_PLUGIN_DIR" ) @@ -23,7 +23,7 @@ func PluginDir() (string, error) { if err != nil { return "", fmt.Errorf("could not determine home directory: %w", err) } - return filepath.Join(home, defaultOSIDir, pluginsSubdir), nil + return filepath.Join(home, defaultOssieDir, pluginsSubdir), nil } // EnsurePluginDir ensures the plugin directory exists, creating it if needed. diff --git a/cli/internal/ossiedir/osidir_test.go b/cli/internal/ossiedir/osidir_test.go index 0fe341c..76a8981 100644 --- a/cli/internal/ossiedir/osidir_test.go +++ b/cli/internal/ossiedir/osidir_test.go @@ -26,7 +26,7 @@ func TestPluginDir_default(t *testing.T) { if err != nil { t.Fatalf("could not determine home dir: %v", err) } - want := filepath.Join(home, defaultOSIDir, pluginsSubdir) + want := filepath.Join(home, defaultOssieDir, pluginsSubdir) got, err := PluginDir() if err != nil { From c707545a6c93d432bb2f087fc6b8e92830b0227a Mon Sep 17 00:00:00 2001 From: Quigley Malcolm Date: Tue, 23 Jun 2026 15:33:28 -0500 Subject: [PATCH 08/22] chore(cli): fix .gitignore to ignore cli/ossie build artifact MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The osi → ossie rename missed the gitignore entry, so the local build artifact cli/ossie would no longer be ignored by git. --- .gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 8cf6aa8..5f39ab3 100644 --- a/.gitignore +++ b/.gitignore @@ -3,4 +3,4 @@ # Go CLI cli/dist/ -cli/osi +cli/ossie From 7f9fdb75510e69259b4e4b4b7e8a8ad856060347 Mon Sep 17 00:00:00 2001 From: Quigley Malcolm Date: Wed, 24 Jun 2026 16:11:52 -0500 Subject: [PATCH 09/22] chore(ossiedir): rename osidir.go and osidir_test.go to ossiedir MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit File names were inconsistent with the package directory name (ossiedir/). Pure rename — no code changes. --- cli/internal/ossiedir/{osidir.go => ossiedir.go} | 0 cli/internal/ossiedir/{osidir_test.go => ossiedir_test.go} | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename cli/internal/ossiedir/{osidir.go => ossiedir.go} (100%) rename cli/internal/ossiedir/{osidir_test.go => ossiedir_test.go} (100%) diff --git a/cli/internal/ossiedir/osidir.go b/cli/internal/ossiedir/ossiedir.go similarity index 100% rename from cli/internal/ossiedir/osidir.go rename to cli/internal/ossiedir/ossiedir.go diff --git a/cli/internal/ossiedir/osidir_test.go b/cli/internal/ossiedir/ossiedir_test.go similarity index 100% rename from cli/internal/ossiedir/osidir_test.go rename to cli/internal/ossiedir/ossiedir_test.go From d11a37524cfedd6fce5b8e7d9adae8938505d24d Mon Sep 17 00:00:00 2001 From: Quigley Malcolm Date: Mon, 15 Jun 2026 10:11:37 -0500 Subject: [PATCH 10/22] feat(cli): add plugin discovery infrastructure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Downstream segments (convert, plugin list, plugin install) all need a way to find and parse installed plugins. This adds the shared foundation: a typed Plugin struct and a Discover() function that scans ~/.ossie/plugins/ for valid plugin.yaml files. Design decisions: - internal/plugin accepts pluginsDir as a parameter rather than calling ossiedir.PluginDir() internally — keeps the package testable without env var manipulation - plugin.yaml supports both ossie_* (preferred) and osi_* (deprecated fallback) key families to avoid breaking plugins written before the OSI → OSSIE rename; ossie_* wins when both are present - Malformed plugin dirs emit a warning to an io.Writer and are skipped; only an unreadable plugins directory is a hard error, matching the behavior specified in the architecture doc - Non-directory entries in the plugins dir are silently skipped (no warning); non-existent dir returns nil, nil Caveats: - Symlinked plugin directories are not yet handled — os.ReadDir reports symlinks with ModeSymlink, not IsDir(); a TODO comment marks the location for a future follow-up - cmd/plugin/list.go wiring is deferred to P1, which also requires the embedded registry before the full table output can be rendered --- cli/go.mod | 5 +- cli/go.sum | 3 + cli/internal/plugin/discover.go | 72 +++++++ cli/internal/plugin/discover_test.go | 299 +++++++++++++++++++++++++++ cli/internal/plugin/plugin.go | 123 +++++++++++ 5 files changed, 501 insertions(+), 1 deletion(-) create mode 100644 cli/internal/plugin/discover.go create mode 100644 cli/internal/plugin/discover_test.go create mode 100644 cli/internal/plugin/plugin.go diff --git a/cli/go.mod b/cli/go.mod index a828425..d17729d 100644 --- a/cli/go.mod +++ b/cli/go.mod @@ -2,7 +2,10 @@ module github.com/open-semantic-interchange/ossie/cli go 1.22 -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 diff --git a/cli/go.sum b/cli/go.sum index a6ee3e0..47edb24 100644 --- a/cli/go.sum +++ b/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= diff --git a/cli/internal/plugin/discover.go b/cli/internal/plugin/discover.go new file mode 100644 index 0000000..700dec1 --- /dev/null +++ b/cli/internal/plugin/discover.go @@ -0,0 +1,72 @@ +package plugin + +import ( + "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 : +// +// 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 os.IsNotExist(err) { + 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 os.IsNotExist(err) { + return nil, fmt.Errorf("no plugin.yaml found") + } + return nil, fmt.Errorf("could not read plugin.yaml: %w", err) + } + + 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 +} diff --git a/cli/internal/plugin/discover_test.go b/cli/internal/plugin/discover_test.go new file mode 100644 index 0000000..1ed7ce6 --- /dev/null +++ b/cli/internal/plugin/discover_test.go @@ -0,0 +1,299 @@ +package plugin_test + +import ( + "os" + "path/filepath" + "strings" + "testing" + + "github.com/open-semantic-interchange/ossie/cli/internal/plugin" +) + +// validPluginYAML is the canonical plugin.yaml fixture using ossie_* keys. +const validPluginYAML = ` +ossie_plugin_spec: "0.1.0" +ossie_spec_version: ">=0.2.0" +platform: + name: dbt + vendor: dbt Labs +convert: + to_osi: + invoke: ["ossie-plugin-dbt", "to-osi"] + accepts: [".yaml", ".json"] + from_osi: + invoke: ["ossie-plugin-dbt", "from-osi"] +` + +// writePlugin creates a plugin directory under root with the given plugin.yaml content. +func writePlugin(t *testing.T, root, name, content string) string { + t.Helper() + dir := filepath.Join(root, name) + if err := os.MkdirAll(dir, 0755); err != nil { + t.Fatalf("could not create plugin dir: %v", err) + } + if err := os.WriteFile(filepath.Join(dir, "plugin.yaml"), []byte(content), 0644); err != nil { + t.Fatalf("could not write plugin.yaml: %v", err) + } + return dir +} + +func TestDiscover_emptyDir(t *testing.T) { + dir := t.TempDir() + var stderr strings.Builder + + plugins, err := plugin.Discover(dir, &stderr) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if len(plugins) != 0 { + t.Errorf("expected no plugins, got %d", len(plugins)) + } + if stderr.Len() != 0 { + t.Errorf("expected no warnings, got: %q", stderr.String()) + } +} + +func TestDiscover_nonExistentDir(t *testing.T) { + var stderr strings.Builder + + plugins, err := plugin.Discover("/this/path/does/not/exist", &stderr) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if plugins != nil { + t.Errorf("expected nil slice, got %v", plugins) + } +} + +func TestDiscover_validPlugin(t *testing.T) { + root := t.TempDir() + pluginDir := writePlugin(t, root, "dbt", validPluginYAML) + var stderr strings.Builder + + plugins, err := plugin.Discover(root, &stderr) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if len(plugins) != 1 { + t.Fatalf("expected 1 plugin, got %d", len(plugins)) + } + p := plugins[0] + if p.Path != pluginDir { + t.Errorf("Path: got %q, want %q", p.Path, pluginDir) + } + if p.Platform.Name != "dbt" { + t.Errorf("Platform.Name: got %q, want %q", p.Platform.Name, "dbt") + } + if p.Platform.Vendor != "dbt Labs" { + t.Errorf("Platform.Vendor: got %q, want %q", p.Platform.Vendor, "dbt Labs") + } + if p.OSSIEPluginSpec != "0.1.0" { + t.Errorf("OSSIEPluginSpec: got %q, want %q", p.OSSIEPluginSpec, "0.1.0") + } + if p.OSSIESpecVersion != ">=0.2.0" { + t.Errorf("OSSIESpecVersion: got %q, want %q", p.OSSIESpecVersion, ">=0.2.0") + } + wantInvoke := []string{"ossie-plugin-dbt", "to-osi"} + if !equalStringSlice(p.Convert.ToOSI.Invoke, wantInvoke) { + t.Errorf("ToOSI.Invoke: got %v, want %v", p.Convert.ToOSI.Invoke, wantInvoke) + } + wantAccepts := []string{".yaml", ".json"} + if !equalStringSlice(p.Convert.ToOSI.Accepts, wantAccepts) { + t.Errorf("ToOSI.Accepts: got %v, want %v", p.Convert.ToOSI.Accepts, wantAccepts) + } + wantFromInvoke := []string{"ossie-plugin-dbt", "from-osi"} + if !equalStringSlice(p.Convert.FromOSI.Invoke, wantFromInvoke) { + t.Errorf("FromOSI.Invoke: got %v, want %v", p.Convert.FromOSI.Invoke, wantFromInvoke) + } + if stderr.Len() != 0 { + t.Errorf("unexpected warning: %q", stderr.String()) + } +} + +func TestDiscover_malformedYAML(t *testing.T) { + root := t.TempDir() + writePlugin(t, root, "bad", "this: is: not: valid: yaml: ][") + var stderr strings.Builder + + plugins, err := plugin.Discover(root, &stderr) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if len(plugins) != 0 { + t.Errorf("expected 0 plugins, got %d", len(plugins)) + } + if !strings.Contains(stderr.String(), filepath.Join(root, "bad")) { + t.Errorf("warning should contain plugin path, got: %q", stderr.String()) + } +} + +func TestDiscover_missingRequiredField(t *testing.T) { + root := t.TempDir() + writePlugin(t, root, "noplat", ` +ossie_plugin_spec: "0.1.0" +ossie_spec_version: ">=0.2.0" +platform: + vendor: dbt Labs +convert: + to_osi: + invoke: ["bin/convert"] + accepts: [".yaml"] + from_osi: + invoke: ["bin/convert"] +`) + var stderr strings.Builder + + plugins, err := plugin.Discover(root, &stderr) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if len(plugins) != 0 { + t.Errorf("expected 0 plugins, got %d", len(plugins)) + } + if !strings.Contains(stderr.String(), filepath.Join(root, "noplat")) { + t.Errorf("warning should contain plugin path, got: %q", stderr.String()) + } +} + +func TestDiscover_missingPluginYAML(t *testing.T) { + root := t.TempDir() + // Create a directory with no plugin.yaml inside it. + if err := os.MkdirAll(filepath.Join(root, "empty-plugin"), 0755); err != nil { + t.Fatal(err) + } + var stderr strings.Builder + + plugins, err := plugin.Discover(root, &stderr) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if len(plugins) != 0 { + t.Errorf("expected 0 plugins, got %d", len(plugins)) + } + if !strings.Contains(stderr.String(), filepath.Join(root, "empty-plugin")) { + t.Errorf("warning should contain plugin path, got: %q", stderr.String()) + } +} + +func TestDiscover_multipleMixed(t *testing.T) { + root := t.TempDir() + writePlugin(t, root, "valid", validPluginYAML) + writePlugin(t, root, "malformed", "bad: yaml: ][") + if err := os.MkdirAll(filepath.Join(root, "no-yaml"), 0755); err != nil { + t.Fatal(err) + } + var stderr strings.Builder + + plugins, err := plugin.Discover(root, &stderr) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if len(plugins) != 1 { + t.Errorf("expected 1 plugin, got %d", len(plugins)) + } + warnings := stderr.String() + if !strings.Contains(warnings, filepath.Join(root, "malformed")) { + t.Errorf("expected warning for malformed, got: %q", warnings) + } + if !strings.Contains(warnings, filepath.Join(root, "no-yaml")) { + t.Errorf("expected warning for no-yaml, got: %q", warnings) + } +} + +func TestDiscover_ossieKeyPreferred(t *testing.T) { + root := t.TempDir() + writePlugin(t, root, "both-keys", ` +ossie_plugin_spec: "ossie-value" +osi_plugin_spec: "osi-value" +ossie_spec_version: ">=1.0.0" +osi_spec_version: ">=0.1.0" +platform: + name: test +convert: + to_osi: + invoke: ["bin/convert"] + accepts: [".yaml"] + from_osi: + invoke: ["bin/convert"] +`) + var stderr strings.Builder + + plugins, err := plugin.Discover(root, &stderr) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if len(plugins) != 1 { + t.Fatalf("expected 1 plugin, got %d", len(plugins)) + } + if plugins[0].OSSIEPluginSpec != "ossie-value" { + t.Errorf("OSSIEPluginSpec: got %q, want %q", plugins[0].OSSIEPluginSpec, "ossie-value") + } + if plugins[0].OSSIESpecVersion != ">=1.0.0" { + t.Errorf("OSSIESpecVersion: got %q, want %q", plugins[0].OSSIESpecVersion, ">=1.0.0") + } +} + +func TestDiscover_osiKeyFallback(t *testing.T) { + root := t.TempDir() + writePlugin(t, root, "osi-only", ` +osi_plugin_spec: "0.2.0" +osi_spec_version: ">=0.1.0" +platform: + name: legacy +convert: + to_osi: + invoke: ["bin/convert"] + accepts: [".json"] + from_osi: + invoke: ["bin/convert"] +`) + var stderr strings.Builder + + plugins, err := plugin.Discover(root, &stderr) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if len(plugins) != 1 { + t.Fatalf("expected 1 plugin, got %d", len(plugins)) + } + if plugins[0].OSSIEPluginSpec != "0.2.0" { + t.Errorf("OSSIEPluginSpec: got %q, want %q", plugins[0].OSSIEPluginSpec, "0.2.0") + } + if plugins[0].OSSIESpecVersion != ">=0.1.0" { + t.Errorf("OSSIESpecVersion: got %q, want %q", plugins[0].OSSIESpecVersion, ">=0.1.0") + } +} + +func TestDiscover_strayFileIgnored(t *testing.T) { + root := t.TempDir() + writePlugin(t, root, "valid", validPluginYAML) + // Place a plain file alongside the plugin directory. + if err := os.WriteFile(filepath.Join(root, "stray.txt"), []byte("not a plugin"), 0644); err != nil { + t.Fatal(err) + } + var stderr strings.Builder + + plugins, err := plugin.Discover(root, &stderr) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if len(plugins) != 1 { + t.Errorf("expected 1 plugin, got %d", len(plugins)) + } + if stderr.Len() != 0 { + t.Errorf("expected no warnings for stray file, got: %q", stderr.String()) + } +} + +// equalStringSlice returns true if a and b contain the same elements in the same order. +func equalStringSlice(a, b []string) bool { + if len(a) != len(b) { + return false + } + for i := range a { + if a[i] != b[i] { + return false + } + } + return true +} diff --git a/cli/internal/plugin/plugin.go b/cli/internal/plugin/plugin.go new file mode 100644 index 0000000..00fa5a1 --- /dev/null +++ b/cli/internal/plugin/plugin.go @@ -0,0 +1,123 @@ +package plugin + +import "errors" + +// Plugin is the parsed and validated representation of a single installed plugin. +// Path is the absolute path to the plugin's installation directory on disk. +type Plugin struct { + Path string // absolute path to plugin dir on disk + OSSIEPluginSpec string + OSSIESpecVersion string + Platform Platform + Setup string // relative path to setup script; empty = no setup + Convert ConvertConfig +} + +// Platform identifies the semantic platform this plugin handles. +type Platform struct { + Name string // required; matched against --from/--to values + Vendor string // optional; human-readable +} + +// ConvertConfig holds both conversion directions. +type ConvertConfig struct { + ToOSI Direction + FromOSI Direction +} + +// Direction describes one conversion direction. +type Direction struct { + Invoke []string // command + args; first element is the executable + Accepts []string // file extensions e.g. [".yaml"]; populated on ToOSI only +} + +// rawPlugin mirrors the on-disk plugin.yaml layout for YAML unmarshaling. +// +// ossie_* keys are the preferred (current brand) names. osi_* keys are +// deprecated aliases kept for backward compatibility with plugins written +// before the OSI → OSSIE rename. When both are present, ossie_* wins. +// TODO: remove osi_* fallback support in a future major version. +type rawPlugin struct { + OSSIEPluginSpec string `yaml:"ossie_plugin_spec"` + OSSIESpecVersion string `yaml:"ossie_spec_version"` + OSIPluginSpec string `yaml:"osi_plugin_spec"` // deprecated + OSISpecVersion string `yaml:"osi_spec_version"` // deprecated + + Platform struct { + Name string `yaml:"name"` + Vendor string `yaml:"vendor"` + } `yaml:"platform"` + + Setup string `yaml:"setup"` + + Convert struct { + ToOSI struct { + Invoke []string `yaml:"invoke"` + Accepts []string `yaml:"accepts"` + } `yaml:"to_osi"` + FromOSI struct { + Invoke []string `yaml:"invoke"` + } `yaml:"from_osi"` + } `yaml:"convert"` +} + +// validate checks that all required fields are present. +// It performs presence checks only — not format validation. +func (r *rawPlugin) validate() error { + pluginSpec := r.OSSIEPluginSpec + if pluginSpec == "" { + pluginSpec = r.OSIPluginSpec + } + specVersion := r.OSSIESpecVersion + if specVersion == "" { + specVersion = r.OSISpecVersion + } + + switch { + case pluginSpec == "": + return errors.New("missing required field: ossie_plugin_spec (or osi_plugin_spec)") + case specVersion == "": + return errors.New("missing required field: ossie_spec_version (or osi_spec_version)") + case r.Platform.Name == "": + return errors.New("missing required field: platform.name") + case len(r.Convert.ToOSI.Invoke) == 0: + return errors.New("missing required field: convert.to_osi.invoke") + case len(r.Convert.ToOSI.Accepts) == 0: + return errors.New("missing required field: convert.to_osi.accepts") + case len(r.Convert.FromOSI.Invoke) == 0: + return errors.New("missing required field: convert.from_osi.invoke") + } + return nil +} + +// toPlugin maps a validated rawPlugin to the exported Plugin type. +// path is the absolute directory path of the plugin's installation. +func (r *rawPlugin) toPlugin(path string) *Plugin { + pluginSpec := r.OSSIEPluginSpec + if pluginSpec == "" { + pluginSpec = r.OSIPluginSpec + } + specVersion := r.OSSIESpecVersion + if specVersion == "" { + specVersion = r.OSISpecVersion + } + return &Plugin{ + Path: path, + OSSIEPluginSpec: pluginSpec, + OSSIESpecVersion: specVersion, + Platform: Platform{ + Name: r.Platform.Name, + Vendor: r.Platform.Vendor, + }, + Setup: r.Setup, + Convert: ConvertConfig{ + ToOSI: Direction{ + Invoke: r.Convert.ToOSI.Invoke, + Accepts: r.Convert.ToOSI.Accepts, + }, + FromOSI: Direction{ + Invoke: r.Convert.FromOSI.Invoke, + }, + }, + } +} From ca72dc9912564f1f5e5e3ea26f2000ab0718fa24 Mon Sep 17 00:00:00 2001 From: Quigley Malcolm Date: Mon, 15 Jun 2026 10:20:24 -0500 Subject: [PATCH 11/22] test(cli): replace equalStringSlice helper with slices.Equal go.mod declares go 1.22 so slices.Equal (stdlib since 1.21) is available. Removes the hand-rolled utility in favour of the standard library equivalent. --- cli/internal/plugin/discover_test.go | 19 ++++--------------- 1 file changed, 4 insertions(+), 15 deletions(-) diff --git a/cli/internal/plugin/discover_test.go b/cli/internal/plugin/discover_test.go index 1ed7ce6..1ff22c2 100644 --- a/cli/internal/plugin/discover_test.go +++ b/cli/internal/plugin/discover_test.go @@ -3,6 +3,7 @@ package plugin_test import ( "os" "path/filepath" + "slices" "strings" "testing" @@ -94,15 +95,15 @@ func TestDiscover_validPlugin(t *testing.T) { t.Errorf("OSSIESpecVersion: got %q, want %q", p.OSSIESpecVersion, ">=0.2.0") } wantInvoke := []string{"ossie-plugin-dbt", "to-osi"} - if !equalStringSlice(p.Convert.ToOSI.Invoke, wantInvoke) { + if !slices.Equal(p.Convert.ToOSI.Invoke, wantInvoke) { t.Errorf("ToOSI.Invoke: got %v, want %v", p.Convert.ToOSI.Invoke, wantInvoke) } wantAccepts := []string{".yaml", ".json"} - if !equalStringSlice(p.Convert.ToOSI.Accepts, wantAccepts) { + if !slices.Equal(p.Convert.ToOSI.Accepts, wantAccepts) { t.Errorf("ToOSI.Accepts: got %v, want %v", p.Convert.ToOSI.Accepts, wantAccepts) } wantFromInvoke := []string{"ossie-plugin-dbt", "from-osi"} - if !equalStringSlice(p.Convert.FromOSI.Invoke, wantFromInvoke) { + if !slices.Equal(p.Convert.FromOSI.Invoke, wantFromInvoke) { t.Errorf("FromOSI.Invoke: got %v, want %v", p.Convert.FromOSI.Invoke, wantFromInvoke) } if stderr.Len() != 0 { @@ -285,15 +286,3 @@ func TestDiscover_strayFileIgnored(t *testing.T) { } } -// equalStringSlice returns true if a and b contain the same elements in the same order. -func equalStringSlice(a, b []string) bool { - if len(a) != len(b) { - return false - } - for i := range a { - if a[i] != b[i] { - return false - } - } - return true -} From afa1813878cde7d8280467a83f35c647e577816f Mon Sep 17 00:00:00 2001 From: Quigley Malcolm Date: Mon, 15 Jun 2026 10:25:51 -0500 Subject: [PATCH 12/22] fix(cli): use errors.Is for ErrNotExist checks in discover os.IsNotExist does not handle wrapped errors correctly. Replace both occurrences with errors.Is(err, os.ErrNotExist), the modern idiom since Go 1.13. --- cli/internal/plugin/discover.go | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/cli/internal/plugin/discover.go b/cli/internal/plugin/discover.go index 700dec1..d49bf3d 100644 --- a/cli/internal/plugin/discover.go +++ b/cli/internal/plugin/discover.go @@ -1,6 +1,7 @@ package plugin import ( + "errors" "fmt" "io" "os" @@ -24,7 +25,7 @@ const pluginYAML = "plugin.yaml" func Discover(pluginsDir string, stderr io.Writer) ([]*Plugin, error) { entries, err := os.ReadDir(pluginsDir) if err != nil { - if os.IsNotExist(err) { + if errors.Is(err, os.ErrNotExist) { return nil, nil } return nil, fmt.Errorf("could not read plugin directory %s: %w", pluginsDir, err) @@ -53,7 +54,7 @@ func loadPlugin(dir string) (*Plugin, error) { yamlPath := filepath.Join(dir, pluginYAML) data, err := os.ReadFile(yamlPath) if err != nil { - if os.IsNotExist(err) { + 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) From 7b8bb117554332c1ddf6c15cad0d15aaec9d984d Mon Sep 17 00:00:00 2001 From: Quigley Malcolm Date: Mon, 15 Jun 2026 10:28:43 -0500 Subject: [PATCH 13/22] test(cli): use t.TempDir for nonexistent dir test fixture Replace hardcoded /this/path/does/not/exist with a path derived from t.TempDir(). The parent is guaranteed to exist by the test harness but the child subdir does not, making the fixture deterministically nonexistent without relying on filesystem assumptions. --- cli/internal/plugin/discover_test.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cli/internal/plugin/discover_test.go b/cli/internal/plugin/discover_test.go index 1ff22c2..557cb4d 100644 --- a/cli/internal/plugin/discover_test.go +++ b/cli/internal/plugin/discover_test.go @@ -57,7 +57,7 @@ func TestDiscover_emptyDir(t *testing.T) { func TestDiscover_nonExistentDir(t *testing.T) { var stderr strings.Builder - plugins, err := plugin.Discover("/this/path/does/not/exist", &stderr) + plugins, err := plugin.Discover(filepath.Join(t.TempDir(), "nonexistent"), &stderr) if err != nil { t.Fatalf("unexpected error: %v", err) } From 8fdac36ae6a94beef3b9a02783003a9daeed56c3 Mon Sep 17 00:00:00 2001 From: Quigley Malcolm Date: Mon, 15 Jun 2026 10:30:10 -0500 Subject: [PATCH 14/22] test(cli): add test coverage for plugin setup field Adds two cases: setup path is correctly parsed when present, and setup is empty string when the field is absent from plugin.yaml. The setup path is consumed by the install segment (P2) when running the plugin's setup script. --- cli/internal/plugin/discover_test.go | 48 ++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/cli/internal/plugin/discover_test.go b/cli/internal/plugin/discover_test.go index 557cb4d..2c82475 100644 --- a/cli/internal/plugin/discover_test.go +++ b/cli/internal/plugin/discover_test.go @@ -286,3 +286,51 @@ func TestDiscover_strayFileIgnored(t *testing.T) { } } +func TestDiscover_setupFieldPopulated(t *testing.T) { + root := t.TempDir() + writePlugin(t, root, "with-setup", ` +ossie_plugin_spec: "0.1.0" +ossie_spec_version: ">=0.2.0" +platform: + name: dbt +setup: bin/setup +convert: + to_osi: + invoke: ["bin/convert", "to-osi"] + accepts: [".yaml"] + from_osi: + invoke: ["bin/convert", "from-osi"] +`) + var stderr strings.Builder + + plugins, err := plugin.Discover(root, &stderr) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if len(plugins) != 1 { + t.Fatalf("expected 1 plugin, got %d", len(plugins)) + } + if plugins[0].Setup != "bin/setup" { + t.Errorf("Setup: got %q, want %q", plugins[0].Setup, "bin/setup") + } + if stderr.Len() != 0 { + t.Errorf("unexpected warning: %q", stderr.String()) + } +} + +func TestDiscover_setupFieldAbsent(t *testing.T) { + root := t.TempDir() + writePlugin(t, root, "no-setup", validPluginYAML) + var stderr strings.Builder + + plugins, err := plugin.Discover(root, &stderr) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if len(plugins) != 1 { + t.Fatalf("expected 1 plugin, got %d", len(plugins)) + } + if plugins[0].Setup != "" { + t.Errorf("Setup: got %q, want empty string", plugins[0].Setup) + } +} From 8747de387c8e9a3e4650508ad207743cfc774370 Mon Sep 17 00:00:00 2001 From: Quigley Malcolm Date: Mon, 15 Jun 2026 10:33:15 -0500 Subject: [PATCH 15/22] docs(cli): document intentional lenient YAML unmarshaling in loadPlugin Unknown fields in plugin.yaml are silently ignored by yaml.Unmarshal. Adding a comment to make clear this is a deliberate forward- compatibility choice, not an oversight. --- cli/internal/plugin/discover.go | 3 +++ 1 file changed, 3 insertions(+) diff --git a/cli/internal/plugin/discover.go b/cli/internal/plugin/discover.go index d49bf3d..7263e32 100644 --- a/cli/internal/plugin/discover.go +++ b/cli/internal/plugin/discover.go @@ -60,6 +60,9 @@ func loadPlugin(dir string) (*Plugin, error) { 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) From fb5069d6eb336570ac9f190d8b3c66f303c99978 Mon Sep 17 00:00:00 2001 From: Quigley Malcolm Date: Tue, 23 Jun 2026 16:20:35 -0500 Subject: [PATCH 16/22] =?UTF-8?q?refactor(plugin):=20rename=20osi=20?= =?UTF-8?q?=E2=86=92=20ossie=20in=20ConvertConfig,=20yaml=20fields,=20and?= =?UTF-8?q?=20invoke=20args?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ConvertConfig.ToOSI/FromOSI and the plugin.yaml fields to_osi/from_osi were left using the old brand name. This sweeps them to ossie consistently with the rest of the CLI rename. to_ossie/from_ossie are now the canonical yaml keys. to_osi/from_osi are kept as deprecated fallbacks in rawPlugin, using the same ossie-wins merge pattern already established for ossie_plugin_spec/osi_plugin_spec. The invoke-arg convention (to-ossie, from-ossie) is updated in all canonical test fixtures; the two backward-compat tests (TestDiscover_ossieKeyPreferred, TestDiscover_osiKeyFallback) intentionally retain to_osi/from_osi since they exercise the deprecated-key path. --- cli/internal/plugin/discover_test.go | 36 +++++++-------- cli/internal/plugin/plugin.go | 66 +++++++++++++++++++++------- 2 files changed, 68 insertions(+), 34 deletions(-) diff --git a/cli/internal/plugin/discover_test.go b/cli/internal/plugin/discover_test.go index 2c82475..71ee85e 100644 --- a/cli/internal/plugin/discover_test.go +++ b/cli/internal/plugin/discover_test.go @@ -18,11 +18,11 @@ platform: name: dbt vendor: dbt Labs convert: - to_osi: - invoke: ["ossie-plugin-dbt", "to-osi"] + to_ossie: + invoke: ["ossie-plugin-dbt", "to-ossie"] accepts: [".yaml", ".json"] - from_osi: - invoke: ["ossie-plugin-dbt", "from-osi"] + from_ossie: + invoke: ["ossie-plugin-dbt", "from-ossie"] ` // writePlugin creates a plugin directory under root with the given plugin.yaml content. @@ -94,17 +94,17 @@ func TestDiscover_validPlugin(t *testing.T) { if p.OSSIESpecVersion != ">=0.2.0" { t.Errorf("OSSIESpecVersion: got %q, want %q", p.OSSIESpecVersion, ">=0.2.0") } - wantInvoke := []string{"ossie-plugin-dbt", "to-osi"} - if !slices.Equal(p.Convert.ToOSI.Invoke, wantInvoke) { - t.Errorf("ToOSI.Invoke: got %v, want %v", p.Convert.ToOSI.Invoke, wantInvoke) + wantInvoke := []string{"ossie-plugin-dbt", "to-ossie"} + if !slices.Equal(p.Convert.ToOssie.Invoke, wantInvoke) { + t.Errorf("ToOssie.Invoke: got %v, want %v", p.Convert.ToOssie.Invoke, wantInvoke) } wantAccepts := []string{".yaml", ".json"} - if !slices.Equal(p.Convert.ToOSI.Accepts, wantAccepts) { - t.Errorf("ToOSI.Accepts: got %v, want %v", p.Convert.ToOSI.Accepts, wantAccepts) + if !slices.Equal(p.Convert.ToOssie.Accepts, wantAccepts) { + t.Errorf("ToOssie.Accepts: got %v, want %v", p.Convert.ToOssie.Accepts, wantAccepts) } - wantFromInvoke := []string{"ossie-plugin-dbt", "from-osi"} - if !slices.Equal(p.Convert.FromOSI.Invoke, wantFromInvoke) { - t.Errorf("FromOSI.Invoke: got %v, want %v", p.Convert.FromOSI.Invoke, wantFromInvoke) + wantFromInvoke := []string{"ossie-plugin-dbt", "from-ossie"} + if !slices.Equal(p.Convert.FromOssie.Invoke, wantFromInvoke) { + t.Errorf("FromOssie.Invoke: got %v, want %v", p.Convert.FromOssie.Invoke, wantFromInvoke) } if stderr.Len() != 0 { t.Errorf("unexpected warning: %q", stderr.String()) @@ -136,10 +136,10 @@ ossie_spec_version: ">=0.2.0" platform: vendor: dbt Labs convert: - to_osi: + to_ossie: invoke: ["bin/convert"] accepts: [".yaml"] - from_osi: + from_ossie: invoke: ["bin/convert"] `) var stderr strings.Builder @@ -295,11 +295,11 @@ platform: name: dbt setup: bin/setup convert: - to_osi: - invoke: ["bin/convert", "to-osi"] + to_ossie: + invoke: ["bin/convert", "to-ossie"] accepts: [".yaml"] - from_osi: - invoke: ["bin/convert", "from-osi"] + from_ossie: + invoke: ["bin/convert", "from-ossie"] `) var stderr strings.Builder diff --git a/cli/internal/plugin/plugin.go b/cli/internal/plugin/plugin.go index 00fa5a1..f370bf7 100644 --- a/cli/internal/plugin/plugin.go +++ b/cli/internal/plugin/plugin.go @@ -21,14 +21,14 @@ type Platform struct { // ConvertConfig holds both conversion directions. type ConvertConfig struct { - ToOSI Direction - FromOSI Direction + ToOssie Direction + FromOssie Direction } // Direction describes one conversion direction. type Direction struct { Invoke []string // command + args; first element is the executable - Accepts []string // file extensions e.g. [".yaml"]; populated on ToOSI only + Accepts []string // file extensions e.g. [".yaml"]; populated on ToOssie only } // rawPlugin mirrors the on-disk plugin.yaml layout for YAML unmarshaling. @@ -51,11 +51,18 @@ type rawPlugin struct { Setup string `yaml:"setup"` Convert struct { - ToOSI struct { + ToOssie struct { + Invoke []string `yaml:"invoke"` + Accepts []string `yaml:"accepts"` + } `yaml:"to_ossie"` + ToOSI struct { // deprecated Invoke []string `yaml:"invoke"` Accepts []string `yaml:"accepts"` } `yaml:"to_osi"` - FromOSI struct { + FromOssie struct { + Invoke []string `yaml:"invoke"` + } `yaml:"from_ossie"` + FromOSI struct { // deprecated Invoke []string `yaml:"invoke"` } `yaml:"from_osi"` } `yaml:"convert"` @@ -73,6 +80,19 @@ func (r *rawPlugin) validate() error { specVersion = r.OSISpecVersion } + toInvoke := r.Convert.ToOssie.Invoke + if len(toInvoke) == 0 { + toInvoke = r.Convert.ToOSI.Invoke + } + toAccepts := r.Convert.ToOssie.Accepts + if len(toAccepts) == 0 { + toAccepts = r.Convert.ToOSI.Accepts + } + fromInvoke := r.Convert.FromOssie.Invoke + if len(fromInvoke) == 0 { + fromInvoke = r.Convert.FromOSI.Invoke + } + switch { case pluginSpec == "": return errors.New("missing required field: ossie_plugin_spec (or osi_plugin_spec)") @@ -80,12 +100,12 @@ func (r *rawPlugin) validate() error { return errors.New("missing required field: ossie_spec_version (or osi_spec_version)") case r.Platform.Name == "": return errors.New("missing required field: platform.name") - case len(r.Convert.ToOSI.Invoke) == 0: - return errors.New("missing required field: convert.to_osi.invoke") - case len(r.Convert.ToOSI.Accepts) == 0: - return errors.New("missing required field: convert.to_osi.accepts") - case len(r.Convert.FromOSI.Invoke) == 0: - return errors.New("missing required field: convert.from_osi.invoke") + case len(toInvoke) == 0: + return errors.New("missing required field: convert.to_ossie.invoke (or convert.to_osi.invoke)") + case len(toAccepts) == 0: + return errors.New("missing required field: convert.to_ossie.accepts (or convert.to_osi.accepts)") + case len(fromInvoke) == 0: + return errors.New("missing required field: convert.from_ossie.invoke (or convert.from_osi.invoke)") } return nil } @@ -101,6 +121,20 @@ func (r *rawPlugin) toPlugin(path string) *Plugin { if specVersion == "" { specVersion = r.OSISpecVersion } + + toInvoke := r.Convert.ToOssie.Invoke + if len(toInvoke) == 0 { + toInvoke = r.Convert.ToOSI.Invoke + } + toAccepts := r.Convert.ToOssie.Accepts + if len(toAccepts) == 0 { + toAccepts = r.Convert.ToOSI.Accepts + } + fromInvoke := r.Convert.FromOssie.Invoke + if len(fromInvoke) == 0 { + fromInvoke = r.Convert.FromOSI.Invoke + } + return &Plugin{ Path: path, OSSIEPluginSpec: pluginSpec, @@ -111,12 +145,12 @@ func (r *rawPlugin) toPlugin(path string) *Plugin { }, Setup: r.Setup, Convert: ConvertConfig{ - ToOSI: Direction{ - Invoke: r.Convert.ToOSI.Invoke, - Accepts: r.Convert.ToOSI.Accepts, + ToOssie: Direction{ + Invoke: toInvoke, + Accepts: toAccepts, }, - FromOSI: Direction{ - Invoke: r.Convert.FromOSI.Invoke, + FromOssie: Direction{ + Invoke: fromInvoke, }, }, } From bc5abe9e0e030a8d2360e37c44e2bf81c4b800cd Mon Sep 17 00:00:00 2001 From: Quigley Malcolm Date: Tue, 23 Jun 2026 16:27:41 -0500 Subject: [PATCH 17/22] refactor(plugin): drop osi_* backward compat from rawPlugin MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The preemptive osi_* fallback fields (osi_plugin_spec, osi_spec_version, to_osi, from_osi) were added in anticipation of backward compatibility, but no plugins exist yet using that format — the rename is happening before any external consumers. Carrying dead compatibility code with no real users adds noise and keeps osi in the codebase. Drops all deprecated fields and merge logic from rawPlugin, simplifying validate() and toPlugin() back to direct field access. TestDiscover_ossieKeyPreferred and TestDiscover_osiKeyFallback (which existed solely to exercise the now-removed paths) are replaced with TestDiscover_unknownFieldsIgnored, which covers the lenient-YAML behavior (future spec fields are silently tolerated) that discover.go explicitly documents. --- cli/internal/plugin/discover_test.go | 56 ++++-------------- cli/internal/plugin/plugin.go | 88 +++++----------------------- 2 files changed, 26 insertions(+), 118 deletions(-) diff --git a/cli/internal/plugin/discover_test.go b/cli/internal/plugin/discover_test.go index 71ee85e..951f785 100644 --- a/cli/internal/plugin/discover_test.go +++ b/cli/internal/plugin/discover_test.go @@ -201,51 +201,20 @@ func TestDiscover_multipleMixed(t *testing.T) { } } -func TestDiscover_ossieKeyPreferred(t *testing.T) { +func TestDiscover_unknownFieldsIgnored(t *testing.T) { root := t.TempDir() - writePlugin(t, root, "both-keys", ` -ossie_plugin_spec: "ossie-value" -osi_plugin_spec: "osi-value" -ossie_spec_version: ">=1.0.0" -osi_spec_version: ">=0.1.0" + writePlugin(t, root, "extra-fields", ` +ossie_plugin_spec: "0.1.0" +ossie_spec_version: ">=0.2.0" +future_field: "some value" platform: name: test + future_platform_field: "ignored" convert: - to_osi: + to_ossie: invoke: ["bin/convert"] accepts: [".yaml"] - from_osi: - invoke: ["bin/convert"] -`) - var stderr strings.Builder - - plugins, err := plugin.Discover(root, &stderr) - if err != nil { - t.Fatalf("unexpected error: %v", err) - } - if len(plugins) != 1 { - t.Fatalf("expected 1 plugin, got %d", len(plugins)) - } - if plugins[0].OSSIEPluginSpec != "ossie-value" { - t.Errorf("OSSIEPluginSpec: got %q, want %q", plugins[0].OSSIEPluginSpec, "ossie-value") - } - if plugins[0].OSSIESpecVersion != ">=1.0.0" { - t.Errorf("OSSIESpecVersion: got %q, want %q", plugins[0].OSSIESpecVersion, ">=1.0.0") - } -} - -func TestDiscover_osiKeyFallback(t *testing.T) { - root := t.TempDir() - writePlugin(t, root, "osi-only", ` -osi_plugin_spec: "0.2.0" -osi_spec_version: ">=0.1.0" -platform: - name: legacy -convert: - to_osi: - invoke: ["bin/convert"] - accepts: [".json"] - from_osi: + from_ossie: invoke: ["bin/convert"] `) var stderr strings.Builder @@ -255,13 +224,10 @@ convert: t.Fatalf("unexpected error: %v", err) } if len(plugins) != 1 { - t.Fatalf("expected 1 plugin, got %d", len(plugins)) + t.Fatalf("expected 1 plugin, got %d: future spec fields should be silently ignored", len(plugins)) } - if plugins[0].OSSIEPluginSpec != "0.2.0" { - t.Errorf("OSSIEPluginSpec: got %q, want %q", plugins[0].OSSIEPluginSpec, "0.2.0") - } - if plugins[0].OSSIESpecVersion != ">=0.1.0" { - t.Errorf("OSSIESpecVersion: got %q, want %q", plugins[0].OSSIESpecVersion, ">=0.1.0") + if stderr.Len() != 0 { + t.Errorf("unexpected warning: %q", stderr.String()) } } diff --git a/cli/internal/plugin/plugin.go b/cli/internal/plugin/plugin.go index f370bf7..aa83cd8 100644 --- a/cli/internal/plugin/plugin.go +++ b/cli/internal/plugin/plugin.go @@ -32,16 +32,9 @@ type Direction struct { } // rawPlugin mirrors the on-disk plugin.yaml layout for YAML unmarshaling. -// -// ossie_* keys are the preferred (current brand) names. osi_* keys are -// deprecated aliases kept for backward compatibility with plugins written -// before the OSI → OSSIE rename. When both are present, ossie_* wins. -// TODO: remove osi_* fallback support in a future major version. type rawPlugin struct { OSSIEPluginSpec string `yaml:"ossie_plugin_spec"` OSSIESpecVersion string `yaml:"ossie_spec_version"` - OSIPluginSpec string `yaml:"osi_plugin_spec"` // deprecated - OSISpecVersion string `yaml:"osi_spec_version"` // deprecated Platform struct { Name string `yaml:"name"` @@ -55,57 +48,28 @@ type rawPlugin struct { Invoke []string `yaml:"invoke"` Accepts []string `yaml:"accepts"` } `yaml:"to_ossie"` - ToOSI struct { // deprecated - Invoke []string `yaml:"invoke"` - Accepts []string `yaml:"accepts"` - } `yaml:"to_osi"` FromOssie struct { Invoke []string `yaml:"invoke"` } `yaml:"from_ossie"` - FromOSI struct { // deprecated - Invoke []string `yaml:"invoke"` - } `yaml:"from_osi"` } `yaml:"convert"` } // validate checks that all required fields are present. // It performs presence checks only — not format validation. func (r *rawPlugin) validate() error { - pluginSpec := r.OSSIEPluginSpec - if pluginSpec == "" { - pluginSpec = r.OSIPluginSpec - } - specVersion := r.OSSIESpecVersion - if specVersion == "" { - specVersion = r.OSISpecVersion - } - - toInvoke := r.Convert.ToOssie.Invoke - if len(toInvoke) == 0 { - toInvoke = r.Convert.ToOSI.Invoke - } - toAccepts := r.Convert.ToOssie.Accepts - if len(toAccepts) == 0 { - toAccepts = r.Convert.ToOSI.Accepts - } - fromInvoke := r.Convert.FromOssie.Invoke - if len(fromInvoke) == 0 { - fromInvoke = r.Convert.FromOSI.Invoke - } - switch { - case pluginSpec == "": - return errors.New("missing required field: ossie_plugin_spec (or osi_plugin_spec)") - case specVersion == "": - return errors.New("missing required field: ossie_spec_version (or osi_spec_version)") + case r.OSSIEPluginSpec == "": + return errors.New("missing required field: ossie_plugin_spec") + case r.OSSIESpecVersion == "": + return errors.New("missing required field: ossie_spec_version") case r.Platform.Name == "": return errors.New("missing required field: platform.name") - case len(toInvoke) == 0: - return errors.New("missing required field: convert.to_ossie.invoke (or convert.to_osi.invoke)") - case len(toAccepts) == 0: - return errors.New("missing required field: convert.to_ossie.accepts (or convert.to_osi.accepts)") - case len(fromInvoke) == 0: - return errors.New("missing required field: convert.from_ossie.invoke (or convert.from_osi.invoke)") + case len(r.Convert.ToOssie.Invoke) == 0: + return errors.New("missing required field: convert.to_ossie.invoke") + case len(r.Convert.ToOssie.Accepts) == 0: + return errors.New("missing required field: convert.to_ossie.accepts") + case len(r.Convert.FromOssie.Invoke) == 0: + return errors.New("missing required field: convert.from_ossie.invoke") } return nil } @@ -113,32 +77,10 @@ func (r *rawPlugin) validate() error { // toPlugin maps a validated rawPlugin to the exported Plugin type. // path is the absolute directory path of the plugin's installation. func (r *rawPlugin) toPlugin(path string) *Plugin { - pluginSpec := r.OSSIEPluginSpec - if pluginSpec == "" { - pluginSpec = r.OSIPluginSpec - } - specVersion := r.OSSIESpecVersion - if specVersion == "" { - specVersion = r.OSISpecVersion - } - - toInvoke := r.Convert.ToOssie.Invoke - if len(toInvoke) == 0 { - toInvoke = r.Convert.ToOSI.Invoke - } - toAccepts := r.Convert.ToOssie.Accepts - if len(toAccepts) == 0 { - toAccepts = r.Convert.ToOSI.Accepts - } - fromInvoke := r.Convert.FromOssie.Invoke - if len(fromInvoke) == 0 { - fromInvoke = r.Convert.FromOSI.Invoke - } - return &Plugin{ Path: path, - OSSIEPluginSpec: pluginSpec, - OSSIESpecVersion: specVersion, + OSSIEPluginSpec: r.OSSIEPluginSpec, + OSSIESpecVersion: r.OSSIESpecVersion, Platform: Platform{ Name: r.Platform.Name, Vendor: r.Platform.Vendor, @@ -146,11 +88,11 @@ func (r *rawPlugin) toPlugin(path string) *Plugin { Setup: r.Setup, Convert: ConvertConfig{ ToOssie: Direction{ - Invoke: toInvoke, - Accepts: toAccepts, + Invoke: r.Convert.ToOssie.Invoke, + Accepts: r.Convert.ToOssie.Accepts, }, FromOssie: Direction{ - Invoke: fromInvoke, + Invoke: r.Convert.FromOssie.Invoke, }, }, } From aa56370db8c361702fdd4cf16f9f9ff8bf8d47e1 Mon Sep 17 00:00:00 2001 From: Quigley Malcolm Date: Tue, 23 Jun 2026 16:43:03 -0500 Subject: [PATCH 18/22] feat(plugin): implement basic ossie plugin list command MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Wires plugin list to the discovery infrastructure added in F2. Reads from the resolved plugin directory, prints a NAME/PLATFORM/SPEC table via tabwriter, and falls back to a "no plugins installed" message when the directory is empty or missing. This is a minimal first pass — the full P1 spec calls for cross-referencing against the embedded plugin registry (installed vs. available, latest version, update indicator), which depends on registry embedding (F4) not yet implemented. --- cli/cmd/plugin/list.go | 37 +++++++++++++++++++++++++++++++++---- 1 file changed, 33 insertions(+), 4 deletions(-) diff --git a/cli/cmd/plugin/list.go b/cli/cmd/plugin/list.go index f69e8bb..01f52d0 100644 --- a/cli/cmd/plugin/list.go +++ b/cli/cmd/plugin/list.go @@ -2,17 +2,46 @@ package plugin import ( "fmt" + "os" + "path/filepath" + "text/tabwriter" "github.com/spf13/cobra" + + "github.com/open-semantic-interchange/ossie/cli/internal/ossiedir" + "github.com/open-semantic-interchange/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() } From e6b0d743d8146f03a139792900075808cc6c4fd3 Mon Sep 17 00:00:00 2001 From: Quigley Malcolm Date: Tue, 23 Jun 2026 16:53:02 -0500 Subject: [PATCH 19/22] chore(cli): add make install target for local development go install . names the binary after the module path's last segment (cli) rather than the intended ossie. make install uses go build -o directly into $GOPATH/bin with the correct binary name. --- cli/Makefile | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/cli/Makefile b/cli/Makefile index 9ecbcb7..d1f7d66 100644 --- a/cli/Makefile +++ b/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 ./... From e64ca8fa85af74a729fc48c2218ddff1a6ef1085 Mon Sep 17 00:00:00 2001 From: Quigley Malcolm Date: Mon, 15 Jun 2026 12:33:45 -0500 Subject: [PATCH 20/22] feat(cli): add plugin invocation protocol MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1 (osi convert base) needs a subprocess layer to pipe requests to plugins and receive responses. This adds the Request/Response/Issue envelope types and an Invoke() function that owns the full lifecycle: marshal request to stdin, capture stdout, forward stderr, enforce context timeout, and decode the JSON response. Design decisions: - Invoke takes pluginDir and invoke []string directly rather than *Plugin — decouples the invocation layer from the discovery types and makes the function independently testable - cmd.Stdout assigned as *bytes.Buffer rather than using cmd.Output() — cmd.Output() is incompatible with a pre-assigned cmd.Stderr writer and would silently discard the caller's stderr destination - ctx.Err() checked after cmd.Run() for timeout detection — exec kills the process with SIGKILL and returns "signal: killed", not context.DeadlineExceeded, so the context must be checked explicitly - Issue.Path uses omitempty — an absent key is semantically distinct from an empty string; plugins that have no path omit the field - A non-empty Issues slice is NOT a Go error — the caller (C1) is responsible for inspecting severities and determining exit code Tests use the TestMain subprocess self-invocation pattern: the test binary re-invokes itself with GO_TEST_PLUGIN=1, enters the fake plugin branch in TestMain, and exits without running any tests. This avoids compiling a separate helper binary and works portably. Caveats: - File collection, output writing, issue rendering, and wiring into cmd/convert.go are deferred to C1 --- cli/internal/plugin/invoke.go | 74 ++++++++ cli/internal/plugin/invoke_test.go | 263 +++++++++++++++++++++++++++++ 2 files changed, 337 insertions(+) create mode 100644 cli/internal/plugin/invoke.go create mode 100644 cli/internal/plugin/invoke_test.go diff --git a/cli/internal/plugin/invoke.go b/cli/internal/plugin/invoke.go new file mode 100644 index 0000000..d7e4018 --- /dev/null +++ b/cli/internal/plugin/invoke.go @@ -0,0 +1,74 @@ +package plugin + +import ( + "bytes" + "context" + "encoding/json" + "fmt" + "io" + "os/exec" +) + +// Request is the JSON envelope sent to a plugin on stdin. +type Request struct { + Files map[string]string `json:"files"` +} + +// Response is the JSON envelope received from a plugin on stdout. +type Response struct { + Files map[string]string `json:"files"` + Issues []Issue `json:"issues,omitempty"` +} + +// Issue is a single diagnostic emitted by a plugin during conversion. +// Severity is one of "error", "warning", or "info". +// Path is optional; it is omitted for issues not tied to a specific location. +type Issue struct { + Severity string `json:"severity"` + Message string `json:"message"` + Path string `json:"path,omitempty"` +} + +// Invoke runs a plugin subprocess, pipes req as JSON to its stdin, +// and decodes its stdout as a JSON Response. +// +// pluginDir is used as the working directory for the subprocess so that +// relative paths in the invoke array resolve correctly. +// invoke is the command and its arguments (invoke[0] is the executable). +// pluginStderr receives the plugin's stderr verbatim; pass io.Discard to suppress. +// +// Hard errors: failed to marshal request, process start failure, context +// deadline exceeded, non-zero exit code, or invalid JSON in the response. +// A non-empty Issues slice in the response is NOT itself a Go error — the +// caller is responsible for inspecting severities and setting the exit code. +func Invoke(ctx context.Context, pluginDir string, invoke []string, req Request, pluginStderr io.Writer) (*Response, error) { + reqJSON, err := json.Marshal(req) + if err != nil { + return nil, fmt.Errorf("failed to marshal plugin request: %w", err) + } + + var stdout bytes.Buffer + cmd := exec.CommandContext(ctx, invoke[0], invoke[1:]...) + cmd.Dir = pluginDir + cmd.Stdin = bytes.NewReader(reqJSON) + // Use an explicit buffer rather than cmd.Output() — cmd.Output() is + // incompatible with a pre-assigned cmd.Stderr writer. + cmd.Stdout = &stdout + cmd.Stderr = pluginStderr + + if err := cmd.Run(); err != nil { + // ctx.Err() is the authoritative signal for timeout/cancellation. + // exec.CommandContext kills the process and returns "signal: killed", + // not context.DeadlineExceeded, so we must check ctx.Err() explicitly. + if ctx.Err() != nil { + return nil, fmt.Errorf("plugin timed out: %w", ctx.Err()) + } + return nil, fmt.Errorf("plugin process failed: %w", err) + } + + var resp Response + if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil { + return nil, fmt.Errorf("invalid JSON response from plugin: %w", err) + } + return &resp, nil +} diff --git a/cli/internal/plugin/invoke_test.go b/cli/internal/plugin/invoke_test.go new file mode 100644 index 0000000..8012c88 --- /dev/null +++ b/cli/internal/plugin/invoke_test.go @@ -0,0 +1,263 @@ +package plugin_test + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "io" + "os" + "strings" + "testing" + "time" + + "github.com/open-semantic-interchange/ossie/cli/internal/plugin" +) + +// TestMain handles two roles: +// 1. When GO_TEST_PLUGIN=1 it acts as a fake plugin subprocess, reads stdin, +// and writes a canned response based on GO_TEST_PLUGIN_MODE. +// 2. Otherwise it runs the normal test suite. +func TestMain(m *testing.M) { + if os.Getenv("GO_TEST_PLUGIN") == "1" { + runFakePlugin() + // runFakePlugin calls os.Exit; this line is never reached. + } + os.Exit(m.Run()) +} + +// runFakePlugin implements a minimal plugin subprocess used by invoke tests. +// It reads all of stdin (the JSON request), then dispatches on GO_TEST_PLUGIN_MODE. +func runFakePlugin() { + stdinBytes, err := io.ReadAll(os.Stdin) + if err != nil { + fmt.Fprintln(os.Stderr, "fake plugin: failed to read stdin:", err) + os.Exit(2) + } + + switch mode := os.Getenv("GO_TEST_PLUGIN_MODE"); mode { + case "success": + json.NewEncoder(os.Stdout).Encode(map[string]any{ + "files": map[string]string{"output.yaml": "converted content"}, + }) + + case "warning_issue": + json.NewEncoder(os.Stdout).Encode(map[string]any{ + "files": map[string]string{"output.yaml": "converted content"}, + "issues": []map[string]string{ + {"severity": "warning", "message": "some warning", "path": "input.yaml"}, + }, + }) + + case "error_issue": + json.NewEncoder(os.Stdout).Encode(map[string]any{ + "files": map[string]string{}, + "issues": []map[string]string{ + {"severity": "error", "message": "conversion failed"}, + }, + }) + + case "invalid_json": + fmt.Fprint(os.Stdout, "not json") + + case "stderr_output": + fmt.Fprint(os.Stderr, "stderr from plugin") + json.NewEncoder(os.Stdout).Encode(map[string]any{ + "files": map[string]string{"output.yaml": "ok"}, + }) + + case "nonzero_exit": + os.Exit(1) + + case "timeout": + time.Sleep(30 * time.Second) + + case "echo_request": + // Echo the raw stdin bytes back in files["received_request"] so the + // test can assert the plugin received the correct request JSON. + json.NewEncoder(os.Stdout).Encode(map[string]any{ + "files": map[string]string{"received_request": string(stdinBytes)}, + }) + + default: + fmt.Fprintln(os.Stderr, "fake plugin: unknown mode:", mode) + os.Exit(2) + } + + os.Exit(0) +} + +// fakePluginInvoke sets up env vars for the fake plugin and returns the +// invoke slice. The test binary re-invokes itself with -test.run=^$ so that +// no tests run in the child — TestMain sees GO_TEST_PLUGIN=1 and exits early. +func fakePluginInvoke(t *testing.T, mode string) []string { + t.Helper() + t.Setenv("GO_TEST_PLUGIN", "1") + t.Setenv("GO_TEST_PLUGIN_MODE", mode) + return []string{os.Args[0], "-test.run=^$"} +} + +func TestInvoke_success(t *testing.T) { + invoke := fakePluginInvoke(t, "success") + ctx := context.Background() + + resp, err := plugin.Invoke(ctx, t.TempDir(), invoke, plugin.Request{Files: map[string]string{}}, io.Discard) + + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if resp == nil { + t.Fatal("expected non-nil response") + } + if _, ok := resp.Files["output.yaml"]; !ok { + t.Errorf("expected output.yaml in response files, got: %v", resp.Files) + } + if len(resp.Issues) != 0 { + t.Errorf("expected no issues, got %d", len(resp.Issues)) + } +} + +func TestInvoke_warningIssue(t *testing.T) { + invoke := fakePluginInvoke(t, "warning_issue") + ctx := context.Background() + + resp, err := plugin.Invoke(ctx, t.TempDir(), invoke, plugin.Request{}, io.Discard) + + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if len(resp.Files) != 1 { + t.Errorf("expected 1 output file, got %d", len(resp.Files)) + } + if len(resp.Issues) != 1 { + t.Fatalf("expected 1 issue, got %d", len(resp.Issues)) + } + if resp.Issues[0].Severity != "warning" { + t.Errorf("issue severity: got %q, want %q", resp.Issues[0].Severity, "warning") + } +} + +func TestInvoke_errorIssue(t *testing.T) { + invoke := fakePluginInvoke(t, "error_issue") + ctx := context.Background() + + // An error-severity issue is NOT a Go error — Invoke must return nil err. + resp, err := plugin.Invoke(ctx, t.TempDir(), invoke, plugin.Request{}, io.Discard) + + if err != nil { + t.Fatalf("unexpected Go error: %v", err) + } + if len(resp.Issues) != 1 { + t.Fatalf("expected 1 issue, got %d", len(resp.Issues)) + } + if resp.Issues[0].Severity != "error" { + t.Errorf("issue severity: got %q, want %q", resp.Issues[0].Severity, "error") + } +} + +func TestInvoke_invalidResponseJSON(t *testing.T) { + invoke := fakePluginInvoke(t, "invalid_json") + ctx := context.Background() + + resp, err := plugin.Invoke(ctx, t.TempDir(), invoke, plugin.Request{}, io.Discard) + + if err == nil { + t.Fatal("expected error for invalid JSON response, got nil") + } + if resp != nil { + t.Errorf("expected nil response, got %+v", resp) + } +} + +func TestInvoke_nonZeroExit(t *testing.T) { + invoke := fakePluginInvoke(t, "nonzero_exit") + ctx := context.Background() + + resp, err := plugin.Invoke(ctx, t.TempDir(), invoke, plugin.Request{}, io.Discard) + + if err == nil { + t.Fatal("expected error for non-zero exit, got nil") + } + if resp != nil { + t.Errorf("expected nil response, got %+v", resp) + } +} + +func TestInvoke_stderrForwarded(t *testing.T) { + invoke := fakePluginInvoke(t, "stderr_output") + ctx := context.Background() + var buf strings.Builder + + _, err := plugin.Invoke(ctx, t.TempDir(), invoke, plugin.Request{}, &buf) + + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if !strings.Contains(buf.String(), "stderr from plugin") { + t.Errorf("expected stderr content in writer, got: %q", buf.String()) + } +} + +func TestInvoke_stderrSuppressed(t *testing.T) { + invoke := fakePluginInvoke(t, "stderr_output") + ctx := context.Background() + + // Passing io.Discard must not panic and must return a valid response. + resp, err := plugin.Invoke(ctx, t.TempDir(), invoke, plugin.Request{}, io.Discard) + + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if resp == nil { + t.Fatal("expected non-nil response") + } +} + +func TestInvoke_timeout(t *testing.T) { + invoke := fakePluginInvoke(t, "timeout") + ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond) + defer cancel() + + resp, err := plugin.Invoke(ctx, t.TempDir(), invoke, plugin.Request{}, io.Discard) + + if err == nil { + t.Fatal("expected timeout error, got nil") + } + if resp != nil { + t.Errorf("expected nil response on timeout, got %+v", resp) + } + if !errors.Is(err, context.DeadlineExceeded) { + t.Errorf("expected DeadlineExceeded in error chain, got: %v", err) + } +} + +func TestInvoke_requestPayloadReachesPlugin(t *testing.T) { + invoke := fakePluginInvoke(t, "echo_request") + ctx := context.Background() + + req := plugin.Request{ + Files: map[string]string{ + "core/orders.yaml": "version: 2\nmodels:\n - name: orders", + }, + } + + resp, err := plugin.Invoke(ctx, t.TempDir(), invoke, req, io.Discard) + + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + raw, ok := resp.Files["received_request"] + if !ok { + t.Fatal("expected received_request key in response files") + } + + // Decode the echoed request and compare — avoids brittle JSON key-ordering checks. + var echoed plugin.Request + if err := json.Unmarshal([]byte(raw), &echoed); err != nil { + t.Fatalf("could not decode echoed request: %v", err) + } + want := req.Files["core/orders.yaml"] + if echoed.Files["core/orders.yaml"] != want { + t.Errorf("echoed file content:\ngot: %q\nwant: %q", echoed.Files["core/orders.yaml"], want) + } +} From 3c4f5ec6fad80ed9f60a88359ac132d11a8f9926 Mon Sep 17 00:00:00 2001 From: Quigley Malcolm Date: Mon, 15 Jun 2026 13:48:54 -0500 Subject: [PATCH 21/22] fix(cli): normalise nil Request.Files to empty map before marshaling A Request with nil Files marshals as {"files":null} rather than {"files":{}}. Plugins that iterate over the files object may crash on a null value. Guard added at the top of Invoke(); test added to verify the wire format is always an object. --- cli/internal/plugin/invoke.go | 5 +++++ cli/internal/plugin/invoke_test.go | 18 ++++++++++++++++++ 2 files changed, 23 insertions(+) diff --git a/cli/internal/plugin/invoke.go b/cli/internal/plugin/invoke.go index d7e4018..10f3b4a 100644 --- a/cli/internal/plugin/invoke.go +++ b/cli/internal/plugin/invoke.go @@ -42,6 +42,11 @@ type Issue struct { // A non-empty Issues slice in the response is NOT itself a Go error — the // caller is responsible for inspecting severities and setting the exit code. func Invoke(ctx context.Context, pluginDir string, invoke []string, req Request, pluginStderr io.Writer) (*Response, error) { + // Normalise nil to empty map so plugins always receive {"files":{}} not {"files":null}. + if req.Files == nil { + req.Files = map[string]string{} + } + reqJSON, err := json.Marshal(req) if err != nil { return nil, fmt.Errorf("failed to marshal plugin request: %w", err) diff --git a/cli/internal/plugin/invoke_test.go b/cli/internal/plugin/invoke_test.go index 8012c88..62550c1 100644 --- a/cli/internal/plugin/invoke_test.go +++ b/cli/internal/plugin/invoke_test.go @@ -261,3 +261,21 @@ func TestInvoke_requestPayloadReachesPlugin(t *testing.T) { t.Errorf("echoed file content:\ngot: %q\nwant: %q", echoed.Files["core/orders.yaml"], want) } } + +func TestInvoke_nilFilesNormalisedToEmptyObject(t *testing.T) { + // A Request with nil Files must marshal as {"files":{}} not {"files":null}. + // Plugins receiving null instead of an object may crash on iteration. + invoke := fakePluginInvoke(t, "echo_request") + ctx := context.Background() + + resp, err := plugin.Invoke(ctx, t.TempDir(), invoke, plugin.Request{}, io.Discard) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + raw := resp.Files["received_request"] + + // The echoed bytes must contain `"files":{}` not `"files":null`. + if !strings.Contains(raw, `"files":{}`) { + t.Errorf("expected files to be serialised as {}, got: %s", raw) + } +} From f2f493ef18b3265065f131cfe0f1025460165e1a Mon Sep 17 00:00:00 2001 From: Quigley Malcolm Date: Mon, 15 Jun 2026 14:52:15 -0500 Subject: [PATCH 22/22] fix(cli): guard against empty invoke slice in Invoke An empty invoke slice would panic with an index out of range on invoke[0]. While F2 validation prevents this in normal usage, an explicit check with a descriptive error is safer and makes the failure mode obvious if the invariant is ever violated. --- cli/internal/plugin/invoke.go | 4 ++++ cli/internal/plugin/invoke_test.go | 13 +++++++++++++ 2 files changed, 17 insertions(+) diff --git a/cli/internal/plugin/invoke.go b/cli/internal/plugin/invoke.go index 10f3b4a..17bf848 100644 --- a/cli/internal/plugin/invoke.go +++ b/cli/internal/plugin/invoke.go @@ -42,6 +42,10 @@ type Issue struct { // A non-empty Issues slice in the response is NOT itself a Go error — the // caller is responsible for inspecting severities and setting the exit code. func Invoke(ctx context.Context, pluginDir string, invoke []string, req Request, pluginStderr io.Writer) (*Response, error) { + if len(invoke) == 0 { + return nil, fmt.Errorf("plugin invoke command is empty") + } + // Normalise nil to empty map so plugins always receive {"files":{}} not {"files":null}. if req.Files == nil { req.Files = map[string]string{} diff --git a/cli/internal/plugin/invoke_test.go b/cli/internal/plugin/invoke_test.go index 62550c1..b2edf43 100644 --- a/cli/internal/plugin/invoke_test.go +++ b/cli/internal/plugin/invoke_test.go @@ -279,3 +279,16 @@ func TestInvoke_nilFilesNormalisedToEmptyObject(t *testing.T) { t.Errorf("expected files to be serialised as {}, got: %s", raw) } } + +func TestInvoke_emptyInvokeReturnsError(t *testing.T) { + ctx := context.Background() + + resp, err := plugin.Invoke(ctx, t.TempDir(), []string{}, plugin.Request{}, io.Discard) + + if err == nil { + t.Fatal("expected error for empty invoke slice, got nil") + } + if resp != nil { + t.Errorf("expected nil response, got %+v", resp) + } +}