feat(cli): machine-readable output for editor and automation integrations

README.md

@@ -66,11 +66,13 @@ microcks [command] [flags]
 | `login`      | Log in to a Microcks instance using Keycloak credentials | [`login`](documentation/cmd/login.md)           |
 | `logout`     | Log out and remove authentication from a given context   | [`logout`](documentation/cmd/logout.md)         |
 | `context`    | Manage CLI contexts (list, use, delete)                  | [`context`](documentation/cmd/context.md)       |
+| `capabilities` | List machine-readable CLI capabilities                 | [`capabilities`](documentation/cmd/capabilities.md) |
 | `start`      | Start a local Microcks instance via Docker/Podman        | [`start`](documentation/cmd/start.md)           |
 | `stop`       | Stop a local Microcks instance                           | [`stop`](documentation/cmd/stop.md)             |
 | `import`     | Import API spec files from local filesystem              | [`import`](documentation/cmd/import.md)         |
 | `import-dir`  | Scan a directory and import API spec files.              | [`import-dir`](documentation/cmd/importDir.md)     |
 | `import-url` | Import API spec files directly from a remote URL         | [`import-url`](documentation/cmd/importUrl.md) |
+| `service`    | List and inspect Microcks services                       | [`service`](documentation/cmd/service.md)       |
 | `test`       | Run tests against a deployed API using selected runner   | [`test`](documentation/cmd/test.md)             |
 | `version`    | Print Microcks CLI version                               | [`version`](documentation/cmd/version.md)       |
 

cmd/capabilities.go

@@ -0,0 +1,104 @@
+/*
+ * Copyright The Microcks Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package cmd
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/microcks/microcks-cli/pkg/errors"
+	"github.com/microcks/microcks-cli/pkg/output"
+	"github.com/microcks/microcks-cli/version"
+	"github.com/spf13/cobra"
+)
+
+const capabilitiesSchemaVersion = "v1"
+
+var supportedCapabilities = []string{
+	"auth.login",
+	"auth.login.sso",
+	"auth.logout",
+	"context.list",
+	"context.list.json",
+	"context.use",
+	"context.use.json",
+	"context.delete",
+	"context.delete.json",
+	"instance.start",
+	"instance.start.json",
+	"instance.stop",
+	"artifact.import.file",
+	"artifact.import.file.json",
+	"artifact.import.file.watch",
+	"artifact.import.directory",
+	"artifact.import.url",
+	"service.list.json",
+	"service.get.json",
+	"test.run",
+	"test.run.output.json",
+	"test.run.output.yaml",
+	"test.run.output.github-actions",
+	"test.dry-run",
+	"test.dry-run.watch",
+	"test.dry-run.watch.events.json",
+	"test.list.json",
+	"test.get.json",
+}
+
+type capabilitiesDocument struct {
+	SchemaVersion string   `json:"schemaVersion"`
+	CLIVersion    string   `json:"cliVersion"`
+	Capabilities  []string `json:"capabilities"`
+}
+
+func NewCapabilitiesCommand() *cobra.Command {
+	var outputFormat string
+
+	command := &cobra.Command{
+		Use:   "capabilities",
+		Short: "List machine-readable Microcks CLI capabilities",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if !output.IsTextOrJSON(outputFormat) {
+				return errors.Wrapf(errors.KindUsage, "--output must be one of: text, json")
+			}
+
+			document := capabilitiesDocument{
+				SchemaVersion: capabilitiesSchemaVersion,
+				CLIVersion:    version.Version,
+				Capabilities:  supportedCapabilities,
+			}
+			if outputFormat == "json" {
+				return errors.Wrap(
+					errors.KindGeneric,
+					output.WriteJSON(os.Stdout, document),
+				)
+			}
+
+			for _, capability := range document.Capabilities {
+				if _, err := fmt.Fprintln(os.Stdout, capability); err != nil {
+					return errors.Wrap(
+						errors.KindEnvironment,
+						fmt.Errorf("writing capabilities output: %w", err),
+					)
+				}
+			}
+			return nil
+		},
+	}
+	command.Flags().StringVar(&outputFormat, "output", "text", "Output format: text or json")
+	return command
+}

cmd/capabilities_test.go

@@ -0,0 +1,88 @@
+/*
+ * Copyright The Microcks Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package cmd
+
+import (
+	"encoding/json"
+	"slices"
+	"testing"
+)
+
+func TestCapabilitiesCommandOutputsJSON(t *testing.T) {
+	out, err := executeCLIForTest(t, "capabilities", "--output", "json")
+	if err != nil {
+		t.Fatalf("command returned error: %v", err)
+	}
+
+	var document capabilitiesDocument
+	if err := json.Unmarshal([]byte(out), &document); err != nil {
+		t.Fatalf("output is not valid JSON: %v", err)
+	}
+	if document.SchemaVersion != capabilitiesSchemaVersion {
+		t.Fatalf("unexpected schema version: %s", document.SchemaVersion)
+	}
+	if document.CLIVersion == "" {
+		t.Fatal("expected a CLI version")
+	}
+	expectedCapabilities := []string{
+		"auth.login",
+		"auth.login.sso",
+		"auth.logout",
+		"context.list",
+		"context.list.json",
+		"context.use",
+		"context.use.json",
+		"context.delete",
+		"context.delete.json",
+		"instance.start",
+		"instance.start.json",
+		"instance.stop",
+		"artifact.import.file",
+		"artifact.import.file.json",
+		"artifact.import.file.watch",
+		"artifact.import.directory",
+		"artifact.import.url",
+		"service.list.json",
+		"service.get.json",
+		"test.run",
+		"test.run.output.json",
+		"test.run.output.yaml",
+		"test.run.output.github-actions",
+		"test.dry-run",
+		"test.dry-run.watch",
+		"test.dry-run.watch.events.json",
+		"test.list.json",
+		"test.get.json",
+	}
+	if !slices.Equal(document.Capabilities, expectedCapabilities) {
+		t.Fatalf("unexpected capabilities:\n got: %#v\nwant: %#v", document.Capabilities, expectedCapabilities)
+	}
+
+	seen := make(map[string]struct{}, len(document.Capabilities))
+	for _, capability := range document.Capabilities {
+		if _, duplicate := seen[capability]; duplicate {
+			t.Errorf("duplicate capability %q", capability)
+		}
+		seen[capability] = struct{}{}
+	}
+}
+
+func TestCapabilitiesCommandRejectsUnsupportedOutput(t *testing.T) {
+	_, err := executeCLIForTest(t, "capabilities", "--output", "yaml")
+	if err == nil {
+		t.Fatal("expected unsupported output format to fail")
+	}
+}

cmd/cmd.go

@@ -43,7 +43,9 @@ func NewCommand() (*cobra.Command, error) {
 	command.AddCommand(NewImportCommand(&clientOpts))
 	command.AddCommand(NewImportDirCommand(&clientOpts))
 	command.AddCommand(NewVersionCommand())
+	command.AddCommand(NewCapabilitiesCommand())
 	command.AddCommand(NewTestCommand(&clientOpts))
+	command.AddCommand(NewServiceCommand(&clientOpts))
 	command.AddCommand(NewImportURLCommand(&clientOpts))
 	command.AddCommand(NewStartCommand(&clientOpts))
 	command.AddCommand(NewStopCommand(&clientOpts))

cmd/command_client.go

@@ -0,0 +1,81 @@
+/*
+ * Copyright The Microcks Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package cmd
+
+import (
+	"github.com/microcks/microcks-cli/pkg/config"
+	"github.com/microcks/microcks-cli/pkg/connectors"
+	"github.com/microcks/microcks-cli/pkg/errors"
+)
+
+func newCommandClient(globalClientOpts *connectors.ClientOptions) (connectors.MicrocksClient, string, error) {
+	config.InsecureTLS = globalClientOpts.InsecureTLS
+	config.CaCertPaths = globalClientOpts.CaCertPaths
+	config.Verbose = globalClientOpts.Verbose
+
+	if globalClientOpts.ServerAddr != "" {
+		mc, err := connectors.NewMicrocksClient(globalClientOpts.ServerAddr)
+		if err != nil {
+			return nil, "", err
+		}
+
+		if globalClientOpts.ClientId != "" && globalClientOpts.ClientSecret != "" {
+			keycloakURL, err := mc.GetKeycloakURL()
+			if err != nil {
+				return nil, "", err
+			}
+
+			oauthToken := "unauthenticated-token"
+			if keycloakURL != "null" {
+				kc, err := connectors.NewKeycloakClient(keycloakURL, globalClientOpts.ClientId, globalClientOpts.ClientSecret)
+				if err != nil {
+					return nil, "", err
+				}
+
+				oauthToken, err = kc.ConnectAndGetToken()
+				if err != nil {
+					return nil, "", err
+				}
+			}
+			mc.SetOAuthToken(oauthToken)
+		}
+		return mc, globalClientOpts.ServerAddr, nil
+	}
+
+	localConfig, err := config.ReadLocalConfig(globalClientOpts.ConfigPath)
+	if err != nil {
+		return nil, "", err
+	}
+	if localConfig == nil {
+		return nil, "", errors.Wrapf(errors.KindUsage, "please login to perform this operation")
+	}
+
+	clientOpts := *globalClientOpts
+	if clientOpts.Context == "" {
+		clientOpts.Context = localConfig.CurrentContext
+	}
+
+	mc, err := connectors.NewClient(clientOpts)
+	if err != nil {
+		return nil, "", err
+	}
+
+	ctx, err := localConfig.ResolveContext(clientOpts.Context)
+	if err != nil {
+		return nil, "", errors.Wrap(errors.KindNotFound, err)
+	}
+	return mc, ctx.Server.Server, nil
+}