External Plugins

Deprecated

External Plugins are deprecated and superseded by gRPC Plugins. Future development and performance optimizations will focus on the gRPC interface.

The ExternalPlugin kind allows you to integrate any external tool or script into swcat. The tool runs as a subprocess, communicating with swcat via standard input (stdin) and standard output (stdout) using JSON.

Configuration

External plugins are configured in plugins.yml.

Field	Type	Description
`command`	`string`	Required. The executable to run (e.g., `java`, `python`, `node`, or a script path).
`args`	`[]string`	Command-line arguments passed to the executable.
`verbose`	`bool`	If `true`, logs input and output JSON payloads to the console for debugging.
`config`	`map`	Arbitrary key-value pairs passed to the plugin in the input JSON.

Example:

plugins:
  my-plugin:
    kind: ExternalPlugin
    # ...
    spec:
      command: python3
      args: ["scripts/my_plugin.py"]
      verbose: true
      config:
        key: value

Protocol

Input JSON (stdin)

The plugin receives a JSON object on stdin.

Field	Type	Description
`entity`	`object`	The catalog entity being processed. Contains `metadata` and `spec`.
`config`	`map`	The configuration map defined in `plugins.yml` under `spec.config`.
`tempDir`	`string`	A temporary directory created for this plugin execution. Plugins should write any generated files here.
`args`	`map`	Runtime arguments passed to the plugin invocation (e.g. from previous plugins in a chain).

Example Input:

{
  "entity": {
    "metadata": {
      "name": "component-name",
      "namespace": "default",
      "annotations": { ... },
      "labels": { ... }
    },
    "spec": { ... }
  },
  "config": {
    "key": "value"
  },
  "tempDir": "/tmp/swcat-123abc",
  "args": { ... }
}

Output JSON (stdout)

The plugin must print a single JSON object to stdout. Any other output (logs, debug info) should be printed to stderr.

Field	Type	Description
`success`	`bool`	Required. `true` if the operation succeeded, `false` otherwise.
`error`	`string`	Error message describing the failure. Required if `success` is `false`.
`generatedFiles`	`[]string`	A list of absolute paths to files generated by the plugin. Useful for chaining plugins.
`annotations`	`map`	A map of annotations (key-value pairs) to be added to the entity. Values must be valid JSON types.

Example Output:

{
  "success": true,
  "error": null,
  "generatedFiles": [
    "/tmp/swcat-123abc/plugin-subfolder/file1",
    "/tmp/swcat-123abc/plugin-subfolder/file2"
  ],
  "annotations": {
    "new/annotation": "value"
  }
}

Example: Maven Artifact Extractor

A reference implementation is available in extensions/maven/. This Java application acts as an External Plugin that downloads artifacts from a Maven repository and extracts files from them.

Its Protocol.java contains example Java classes that model the JSON input and output.