componentsdk

Documentation

Overview

Package componentsdk provides tools for component SDK authors. It includes scaffolding, development running, testing, and mock generation.

Index

• func InferBinaryPath(path string) (projectDir, binaryPath string, err error)
• func IsGoProject(dir string) bool
• func ParseKind(s string) (componenttypes.ComponentKind, error)
• func Run(ctx context.Context, opts RunOptions) (int, error)
• func SupportedKinds() []componenttypes.ComponentKind
• func ValidateName(name string) error
• func Watch(ctx context.Context, opts WatchOptions) error
• type Capabilities
  • func GetCapabilities(binaryPath string) (*Capabilities, error)
• type MockOptions
• type MockResult
  • func GenerateMocks(opts MockOptions) (*MockResult, error)
• type RunOptions
• type ScaffoldOptions
• type ScaffoldResult
  • func Scaffold(opts ScaffoldOptions) (*ScaffoldResult, error)
• type TestOptions
• type TestResult
  • func Test(ctx context.Context, opts TestOptions) (*TestResult, error)
• type WatchOptions

Functions

func InferBinaryPath

func InferBinaryPath(path string) (projectDir, binaryPath string, err error)

InferBinaryPath returns the inferred binary path for a Go project. If the path is a directory, the binary name is the directory name. If the path is a file, it's returned as-is.

func IsGoProject

func IsGoProject(dir string) bool

IsGoProject checks if a directory contains a go.mod file.

func ParseKind

func ParseKind(s string) (componenttypes.ComponentKind, error)

ParseKind parses a string into a ComponentKind, returning an error if unsupported.

func Run

func Run(ctx context.Context, opts RunOptions) (int, error)

Run executes a component binary and returns its exit code.

func SupportedKinds

func SupportedKinds() []componenttypes.ComponentKind

SupportedKinds returns the component kinds that support scaffolding.

func ValidateName

func ValidateName(name string) error

ValidateName checks if a component name is valid. Names must match ^[a-z0-9][a-z0-9._-]{0,63}$

func Watch

func Watch(ctx context.Context, opts WatchOptions) error

Watch runs the component in watch mode, rebuilding and rerunning on changes. It blocks until interrupted.

Types

type Capabilities

type Capabilities struct {
	Name        string `json:"name"`
	Kind        string `json:"kind"`
	Version     string `json:"version"`
	Description string `json:"description"`
}

Capabilities represents the JSON from --capabilities.

func GetCapabilities

func GetCapabilities(binaryPath string) (*Capabilities, error)

GetCapabilities runs --capabilities on a binary and parses the output.

type MockOptions

type MockOptions struct {
	// OutputDir is where to write the generated files.
	OutputDir string

	// Kind is the component kind to generate mocks for.
	Kind componenttypes.ComponentKind
}

MockOptions configures mock generation.

type MockResult

type MockResult struct {
	// FilesCreated is the list of files created.
	FilesCreated []string
}

MockResult contains the result of mock generation.

func GenerateMocks

func GenerateMocks(opts MockOptions) (*MockResult, error)

GenerateMocks creates sample input files for testing components.

type RunOptions

type RunOptions struct {
	// BinaryPath is the path to the component binary.
	BinaryPath string

	// Args are the arguments to pass to the binary.
	Args []string

	// Stdin is the input for the binary.
	Stdin io.Reader

	// Stdout is the output for the binary.
	Stdout io.Writer

	// Stderr is the error output for the binary.
	Stderr io.Writer
}

RunOptions configures how to run a local component.

type ScaffoldOptions

type ScaffoldOptions struct {
	// TargetDir is the directory to scaffold into (must exist).
	TargetDir string

	// Name is the component name (without epack-<kind>- prefix).
	Name string

	// Kind is the component kind (tool, collector, remote, utility).
	Kind componenttypes.ComponentKind
}

ScaffoldOptions configures the component scaffolding.

type ScaffoldResult

type ScaffoldResult struct {
	// FilesCreated is the list of files created (relative to TargetDir).
	FilesCreated []string

	// ModulePath is the generated Go module path.
	ModulePath string

	// BinaryName is the generated binary name (e.g., "epack-tool-foo").
	BinaryName string
}

ScaffoldResult contains information about what was scaffolded.

func Scaffold

func Scaffold(opts ScaffoldOptions) (*ScaffoldResult, error)

Scaffold creates a component project in the target directory. The directory must already exist.

type TestOptions

type TestOptions struct {
	// BinaryPath is the path to the component binary to test.
	BinaryPath string

	// Verbose enables detailed test output.
	Verbose bool

	// OnBuildStart is called when building starts (for directory mode).
	OnBuildStart func()

	// OnBuildSuccess is called when building succeeds.
	OnBuildSuccess func()

	// OnBuildFailed is called when building fails.
	OnBuildFailed func(err error)

	// OnTestStart is called when tests start running.
	OnTestStart func(caps *Capabilities)
}

TestOptions configures conformance testing.

type TestResult

type TestResult struct {
	// Passed is true if all tests passed.
	Passed bool

	// ExitCode is the exit code from epack-conformance.
	ExitCode int
}

TestResult contains the result of conformance testing.

func Test

func Test(ctx context.Context, opts TestOptions) (*TestResult, error)

Test runs conformance tests against a component binary. If binaryPath is a directory, it builds the Go project first.

type WatchOptions

type WatchOptions struct {
	// ProjectDir is the Go project directory to watch.
	ProjectDir string

	// BinaryPath is where to build the binary.
	BinaryPath string

	// Args are the arguments to pass to the binary on each run.
	Args []string

	// OnBuildStart is called when a build starts.
	OnBuildStart func()

	// OnBuildSuccess is called when a build succeeds.
	OnBuildSuccess func()

	// OnBuildFailed is called when a build fails.
	OnBuildFailed func(err error)

	// OnRunStart is called when the component starts running.
	OnRunStart func(caps *Capabilities)

	// OnRunExit is called when the component exits.
	OnRunExit func(code int, err error)

	// OnWaiting is called when waiting for changes.
	OnWaiting func()

	// OnChange is called when a file change is detected.
	OnChange func()

	// OnShutdown is called when shutting down.
	OnShutdown func()
}

WatchOptions configures watch mode for component development.