Skip to content

Latest commit

 

History

History
662 lines (364 loc) · 19.6 KB

DOCUMENTATION.md

File metadata and controls

662 lines (364 loc) · 19.6 KB

SDKGenerator SDK

Generated by go-sdk-generator

Documentation for the SDK Generator SDK.

⚙️ This project also comes with CLI tools and commands for ease of use

👷 This project also provides actions for workflow integration

Global Configuration

SDKGeneratorManagerConfiguration

SDKGeneratorManagerConfiguration is the configuration structure used by the SDK manager. It is the main mechanism for passing configuration values into the manager.

The same configuration model is reused by the related CLI entrypoints where applicable.

Fields:

  • Input : string - path to tool definition file (required)

  • Output : string - destination of the generated code (required)

  • Overwrite : bool - regenerate all files (required)

  • TargetedGoVersion : string - targeted go version for the tool (required)

Interface

The manager interface of the SDK is ISDKGeneratorManager.

Mocks for this interface are provided under mocks/ using mockgen, so tests can target the interface rather than a concrete implementation.

Methods:

Generate

Description: Generate the tool

Signature:

Generate(ctx context.Context, logger logs.Loggers) (err error)

Arguments:

  • ctx : context.Context - controls cancellation, deadlines, and other request-scoped values.

  • logger : logs.Loggers - Logger to use for informational generation messages

Returns:

  • err : error - Whether the generation failed or not

CLI Tool

go-sdk-generator

Description: CLI for generating SDK/CLI go tools from a specification following schema

Configuration loading:

The CLI uses configUtils.LoadUsing(...) together with Viper.

Environment variables are prefixed with SDK_GENERATOR.

For workflow integration, prefer the actions when one of them already represents the step you want to run. GitHub can then validate the action metadata and execute the step in a more structured way. When looping, custom orchestration, or more complex parallel execution is needed, it can be preferable to install the binary first and call it directly from later workflow steps.

Effective precedence for command configuration is:

  1. keyring values, when the command enables keyring-backed loading and a non-empty value is available
  2. flag values provided on the command line
  3. environment variables, including values loaded from .env
  4. the configured configuration file, when one is configured and present and its format is supported by Viper
  5. default values

This CLI does not declare a dedicated configuration file path. The underlying loader still supports configuration files through Viper, but this tool does not configure a default configuration file location.

Configuration is loaded and validated at the start of command execution, so configuration errors are surfaced before the underlying manager logic runs.

Logging And Annotations

CLIs expose separate runtime configuration for normal logging and structured annotations.

CLI defaults:

  • logger=console
  • annotation=none

Action defaults:

  • logger=rich
  • annotation=github

Logger modes:

  • console: use the standard generated console logger.
  • rich: use a richer terminal logger built with Charmbracelet Log.
  • file: write normal logs to the path selected by logger_file.
  • none: disable normal log output.
  • custom: use the logger implementation registered by the application during initialisation.

Annotation modes:

  • Annotations are structured status messages separate from normal logs. They are primarily intended for CI systems that can render errors, warnings, and notices with extra context.
  • github: emit GitHub Actions-compatible structured annotations using golang-utils annotation support.
  • none: disable structured annotation output.

Logging and annotations are independent concerns. For example:

  • logger=rich with annotation=none gives richer human-readable terminal logging without CI annotations.
  • logger=rich with annotation=github gives richer terminal logging together with GitHub-compatible annotations, which fall back to standard output.
  • logger=none with annotation=github suppresses normal logs while still allowing advanced GitHub annotations.

Usage examples:

go-sdk-generator generate --logger=console
go-sdk-generator generate --logger=rich
go-sdk-generator generate --logger=file --logger-file=tool.log
go-sdk-generator generate --logger=none
go-sdk-generator generate --logger=custom
go-sdk-generator generate --annotation=github
go-sdk-generator generate --logger=rich --annotation=github

Custom Logger Registration

To use logger=custom, register CustomLoggerDefinition during application initialisation.

Add a file under cmd/generator/ in package generator.

package generator

import (
	"log/slog"
	"os"

	baselogs "github.com/ARM-software/golang-utils/utils/logs"
)

func init() {
	logger, err := baselogs.NewSlogLogger(slog.New(slog.NewJSONHandler(os.Stderr, nil)), "go-sdk-generator")
	if err != nil {
		panic(err)
	}
	CustomLoggerDefinition = logger
}

The command-line user does not supply an arbitrary Go implementation through the CLI. Selecting logger=custom simply chooses the implementation already registered by the application.

If logger=custom is selected without registering CustomLoggerDefinition, the generated CLI returns an error.

Skills:

Linux packages built for this tool also install the skills related to the tool under /etc/go-sdk-generator/.agents/skills.

OCI Images

OCI images are also published to ghcr.io/arm-software/go-sdk-generator for CI integration, reproducible builds, and workflows that prefer not to install the tool locally.

GitHub documents container-registry authentication and package permissions at: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry

On a local machine, if the package is not publicly accessible to the user's account yet, log in to ghcr.io first. With the GitHub CLI installed and already authenticated:

gh auth token | docker login ghcr.io -u "$(gh api user --jq .login)" --password-stdin

If docker run or docker pull fails with 403 Forbidden, the GitHub credentials usually do not have package-read access. The read:packages permission is required, including in CI workflows that need to pull the OCI image. For local-machine use with GitHub CLI credentials, refresh GitHub CLI credentials, then log in to GHCR again:

docker logout ghcr.io
gh auth refresh --scopes read:packages
gh auth token | docker login ghcr.io -u "$(gh api user --jq .login)" --password-stdin

Published variants:

  • :v<version>-alpine
  • :v<version>-ubuntu

Use exact release tags or image digests when the workflow must stay reproducible.

Commands

go-sdk-generator generate

Description: Generate tool/project scaffolding. Run go mod tidy afterwards to resolve the generated module dependencies, then run go generate ./... to execute any generated code-generation directives inside the new project.

Usage:

go-sdk-generator generate [flags]

OCI usage:

docker run --rm ghcr.io/arm-software/go-sdk-generator:v<version>-alpine generate [flags]
docker run --rm ghcr.io/arm-software/go-sdk-generator:v<version>-ubuntu generate [flags]

Flags and environment bindings:

You can pass values as flags on the command line or by setting the corresponding environment variables.

Example flag usage:

go-sdk-generator generate --annotation <value>

Example environment usage:

SDK_GENERATOR_ANNOTATION=<value> go-sdk-generator generate
Configuration Flag Short Environment Required Description

| Annotation (shared) | --annotation | - | SDK_GENERATOR_ANNOTATION | no | Select the implementation used for structured annotations such as errors, warnings, and notices. Allowed values: github, none. |

| Logger (shared) | --logger | - | SDK_GENERATOR_LOGGER | no | Select the implementation used for normal runtime logs. Allowed values: console, rich, file, none, custom. |

| LoggerFile (shared) | --logger-file | - | SDK_GENERATOR_LOGGER_FILE | no | Path to write normal runtime logs when logger is set to file. |

| ShowConfig (shared) | --show-config | - | SDK_GENERATOR_SHOW_CONFIG | no | Show the effective configuration used by this command before execution. |

| Generate | --overwrite | -a | SDK_GENERATOR_OVERWRITE | no | regenerate all files |

| Input | --input | -i | SDK_GENERATOR_INPUT | yes | path to tool definition file |

| Output | --output | -o | SDK_GENERATOR_OUTPUT | yes | destination of the generated code |

| Summary | --summary | - | SDK_GENERATOR_SUMMARY | no | Write a human-readable summary to the selected destination. Allowed values: file, github, output. |

| SummaryFile | --summary-file | - | SDK_GENERATOR_SUMMARY_FILE | no | Path to the summary file when summary is set to file |

| TargetedGo | --go-version | -g | SDK_GENERATOR_GO_VERSION | no | targeted go version for the tool |

Configuration type:

type GenerateConfiguration struct {
	Annotation GenerateAnnotation `mapstructure:"annotation"`
	Generate bool `mapstructure:"overwrite"`
	Input string `mapstructure:"input"`
	Logger GenerateLogger `mapstructure:"logger"`
	LoggerFile string `mapstructure:"logger_file"`
	Output string `mapstructure:"output"`
	ShowConfig bool `mapstructure:"show_config"`
	Summary GenerateSummary `mapstructure:"summary"`
	SummaryFile string `mapstructure:"summary_file"`
	TargetedGo string `mapstructure:"go_version"`
}

Fields:

  • Annotation : GenerateAnnotation - Select the implementation used for structured annotations such as errors, warnings, and notices. Allowed values: github, none.

  • Generate : bool - regenerate all files

  • Input : string - path to tool definition file (required)

  • Logger : GenerateLogger - Select the implementation used for normal runtime logs. Allowed values: console, rich, file, none, custom.

  • LoggerFile : string - Path to write normal runtime logs when logger is set to file.

  • Output : string - destination of the generated code (required)

  • ShowConfig : bool - Show the effective configuration used by this command before execution.

  • Summary : GenerateSummary - Write a human-readable summary to the selected destination. Allowed values: file, github, output.

  • SummaryFile : string - Path to the summary file when summary is set to file

  • TargetedGo : string - targeted go version for the tool

Helper methods:

  • Validate() validates the configuration.
func (cfg *GenerateConfiguration) Validate() error
  • DefaultGenerateConfiguration() returns the default values.
func DefaultGenerateConfiguration() *GenerateConfiguration

go-sdk-generator schema

Description: Run go-sdk-generator schema to dump the embedded manifest schema as JSON for agents and other tooling

Usage:

go-sdk-generator schema [flags]

OCI usage:

docker run --rm ghcr.io/arm-software/go-sdk-generator:v<version>-alpine schema [flags]
docker run --rm ghcr.io/arm-software/go-sdk-generator:v<version>-ubuntu schema [flags]

Flags and environment bindings:

You can pass values as flags on the command line or by setting the corresponding environment variables.

Example flag usage:

go-sdk-generator schema --annotation <value>

Example environment usage:

SDK_GENERATOR_ANNOTATION=<value> go-sdk-generator schema
Configuration Flag Short Environment Required Description

| Annotation (shared) | --annotation | - | SDK_GENERATOR_ANNOTATION | no | Select the implementation used for structured annotations such as errors, warnings, and notices. Allowed values: github, none. |

| Logger (shared) | --logger | - | SDK_GENERATOR_LOGGER | no | Select the implementation used for normal runtime logs. Allowed values: console, rich, file, none, custom. |

| LoggerFile (shared) | --logger-file | - | SDK_GENERATOR_LOGGER_FILE | no | Path to write normal runtime logs when logger is set to file. |

| ShowConfig (shared) | --show-config | - | SDK_GENERATOR_SHOW_CONFIG | no | Show the effective configuration used by this command before execution. |

Configuration type:

type SchemaConfiguration struct {
	Annotation SchemaAnnotation `mapstructure:"annotation"`
	Logger SchemaLogger `mapstructure:"logger"`
	LoggerFile string `mapstructure:"logger_file"`
	ShowConfig bool `mapstructure:"show_config"`
}

Fields:

  • Annotation : SchemaAnnotation - Select the implementation used for structured annotations such as errors, warnings, and notices. Allowed values: github, none.

  • Logger : SchemaLogger - Select the implementation used for normal runtime logs. Allowed values: console, rich, file, none, custom.

  • LoggerFile : string - Path to write normal runtime logs when logger is set to file.

  • ShowConfig : bool - Show the effective configuration used by this command before execution.

Helper methods:

  • Validate() validates the configuration.
func (cfg *SchemaConfiguration) Validate() error
  • DefaultSchemaConfiguration() returns the default values.
func DefaultSchemaConfiguration() *SchemaConfiguration

go-sdk-generator agent

Description: Run go-sdk-generator agent --init to initialise the repo skills under .agents/skills

Usage:

go-sdk-generator agent [flags]

OCI usage:

docker run --rm ghcr.io/arm-software/go-sdk-generator:v<version>-alpine agent [flags]
docker run --rm ghcr.io/arm-software/go-sdk-generator:v<version>-ubuntu agent [flags]

Flags and environment bindings:

You can pass values as flags on the command line or by setting the corresponding environment variables.

Example flag usage:

go-sdk-generator agent --annotation <value>

Example environment usage:

SDK_GENERATOR_ANNOTATION=<value> go-sdk-generator agent
Configuration Flag Short Environment Required Description

| Annotation (shared) | --annotation | - | SDK_GENERATOR_ANNOTATION | no | Select the implementation used for structured annotations such as errors, warnings, and notices. Allowed values: github, none. |

| Logger (shared) | --logger | - | SDK_GENERATOR_LOGGER | no | Select the implementation used for normal runtime logs. Allowed values: console, rich, file, none, custom. |

| LoggerFile (shared) | --logger-file | - | SDK_GENERATOR_LOGGER_FILE | no | Path to write normal runtime logs when logger is set to file. |

| ShowConfig (shared) | --show-config | - | SDK_GENERATOR_SHOW_CONFIG | no | Show the effective configuration used by this command before execution. |

| Init | --init | - | SDK_GENERATOR_INIT | no | install the embedded skills into the current repository |

Configuration type:

type AgentConfiguration struct {
	Annotation AgentAnnotation `mapstructure:"annotation"`
	Init bool `mapstructure:"init"`
	Logger AgentLogger `mapstructure:"logger"`
	LoggerFile string `mapstructure:"logger_file"`
	ShowConfig bool `mapstructure:"show_config"`
}

Fields:

  • Annotation : AgentAnnotation - Select the implementation used for structured annotations such as errors, warnings, and notices. Allowed values: github, none.

  • Init : bool - install the embedded skills into the current repository

  • Logger : AgentLogger - Select the implementation used for normal runtime logs. Allowed values: console, rich, file, none, custom.

  • LoggerFile : string - Path to write normal runtime logs when logger is set to file.

  • ShowConfig : bool - Show the effective configuration used by this command before execution.

Helper methods:

  • Validate() validates the configuration.
func (cfg *AgentConfiguration) Validate() error
  • DefaultAgentConfiguration() returns the default values.
func DefaultAgentConfiguration() *AgentConfiguration

GitHub Action

GitHub Actions are also published so that go-sdk-generator subcommands can be used easily in CI workflows.

Prefer using the actions directly when they already represent one complete workflow step. Prefer the installation action when the goal is only to obtain the tool for later workflow steps, for example when a later step needs to loop, pipe output, perform additional shell processing, or call a script that expects the tool to already be available in the environment. This follows the same general model used by tool-installing actions such as goreleaser/goreleaser-action with install-only and anchore/sbom-action/download-syft.

Skill:

Actions in this repository:

  • actions/install-tool installs go-sdk-generator
  • actions/generate runs go-sdk-generator generate

Use the published installation action to obtain the tool so it can be used in other workflow steps:

- name: Install go-sdk-generator from release
  uses: ARM-software/go-sdk-generator/actions/install-tool@v0
  with:
    workdir: .tools

Use the published action from an official release to perform a particular action [generate] directly:

- name: Run go-sdk-generator generate
  uses: ARM-software/go-sdk-generator/actions/generate@v0
  with:
    # provide the inputs required by the `generate` command here

The actions expose inputs for selecting the release source and installation location. For actions that perform a particular subcommand, the remaining inputs map onto that subcommand's CLI flags. Every action also exposes the cmd output, which resolves to a usable reference for the installed go-sdk-generator command in later workflow steps.

Inputs:

  • action-repo: repository to download releases from; defaults to the repository running the action
  • workdir: working directory where the CLI is run. If later workflow steps need to call the installed tool, use the cmd output rather than inferring its location from this directory.
  • actions/install-tool exposes only installation inputs
  • each action other than the installation one also exposes one input per non-hidden CLI flag for that subcommand, including repeated root inputs shared across commands
  • commands with positional operands also expose an operands input, one operand per line

Outputs:

  • cmd output: a reference to the installed go-sdk-generator command for later workflow steps

The action resolves official releases from the action version:

  • @v0.29.0 installs exactly v0.29.0
  • @v0.29 installs the latest v0.29.x release
  • @v0 installs the latest v0.x.y release
  • @latest installs the latest released version