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

.github/workflows/build-verify.yml

@@ -41,6 +41,19 @@ jobs:
           make clean
           make build-binaries
 
+      - name: Run tests
+        run: go test ./...
+
+      - name: Guard against stray process exits
+        run: |
+          # pkg/* and cmd/* (except cmd/exit.go) must return a classified error,
+          # never exit or panic. Only the main entrypoints exit the process.
+          # See documentation/error-handling.md.
+          if grep -rnE '(os\.Exit|log\.Fatal|panic\()' --include='*.go' cmd pkg | grep -vE '_test\.go|cmd/exit\.go'; then
+            echo "::error::os.Exit/log.Fatal/panic found outside cmd/exit.go — return errors.Wrap(kind, err) instead."
+            exit 1
+          fi
+
       - name: Set environment for branch
         run: |
           set -x

CONTRIBUTING.md

@@ -45,6 +45,13 @@ Microcks has adopted a Code of Conduct that we expect project participants to ad
 
 We use Github to host code, to track issues and feature requests, as well as accept pull requests.
 
+## Error handling
+
+Code under `pkg/` and `cmd/` must return errors, never exit or panic on a runtime
+error: wrap the failure with a Kind (`return errors.Wrap(errors.KindConnection, err)`)
+and let it flow up. Only the `main` entrypoints and `cmd.Handle` exit the process.
+See [documentation/error-handling.md](documentation/error-handling.md); CI enforces this.
+
 ## Issues
 
 [Open an issue](https://github.com/microcks/microcks/issues/new) **only** if you want to report a bug or a feature. Don't open issues for questions or support, instead join our [Discord #support channel](https://microcks.io/discord-invite) or our [GitHub discussions](https://github.com/orgs/microcks/discussions) and ask there. 

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)       |
 
@@ -181,6 +183,51 @@ $ docker run -it quay.io/microcks/microcks-cli:latest microcks test 'Beer Catalo
 ```
 
 
+## Machine-readable test output
+
+`microcks test` accepts `--output` to control how the result is rendered:
+
+| Value | Output |
+| --- | --- |
+| `text` (default) | Human-readable summary |
+| `json` | The full `TestResult` as JSON |
+| `yaml` | The full `TestResult` as YAML |
+| `github-actions` | GitHub Actions workflow commands (annotations + log groups + step summary) |
+
+For machine formats (`json`/`yaml`/`github-actions`), progress goes to **stderr**
+and only the formatted result is written to **stdout**, so it can be piped or
+parsed cleanly:
+
+```bash
+microcks test "Pastry API:1.0.0" http://localhost:8080/api OPEN_API_SCHEMA \
+  --microcksURL=http://localhost:8585/api --output=json > result.json
+```
+
+### GitHub Actions
+
+With `--output=github-actions`, failures surface as `::error::` annotations,
+each operation is wrapped in a collapsible `::group::`, and a per-operation table
+is appended to the job summary (`$GITHUB_STEP_SUMMARY`). Set
+`MICROCKS_ACTIONS_VERBOSE=true` to also emit `::notice::` for passing operations.
+
+```yaml
+# .github/workflows/contract-test.yml
+name: contract-test
+on: [pull_request]
+jobs:
+  contract-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Microcks contract test
+        run: |
+          microcks test "Pastry API:1.0.0" "${{ env.API_URL }}" OPEN_API_SCHEMA \
+            --microcksURL=${{ secrets.MICROCKS_URL }} \
+            --keycloakClientId=${{ secrets.MICROCKS_CLIENT_ID }} \
+            --keycloakClientSecret=${{ secrets.MICROCKS_CLIENT_SECRET }} \
+            --output=github-actions
+```
+
 ## Tekton tasks
 
 This repository also contains different [Tekton](https://tekton.dev/) tasks definitions and sample pipelines. You'll find under the `/tekton` folder the resource for current `v1beta1` Tekton API version and the older `v1alpha1` under `tekton/v1alpha1`.

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.KindEnvironment,
+					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
+}