plugin

package
v0.19.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 13, 2026 License: MIT Imports: 35 Imported by: 6

Documentation

Overview

Package plugin provides the SDK used by sitectl plugins.

Host/plugin RPC uses typed JSON envelopes on the wire, but existing plugin commands still execute through Cobra. For plugin-owned commands, sitectl decodes RPC params into tagged structs, reconstructs the matching argv, and lets Cobra parse the flags and positionals again. This preserves existing BindFlags, hooks, help handling, and passthrough flag behavior while keeping the host/plugin wire format strict and testable.

RPC param structs use these tags:

  • rpc_flags:"name,alias" maps a field to one or more long flags.
  • rpc_pos:"1" maps a string field to a positional argument.
  • rpc_rootfs:"true" marks the rootfs path flag alias.
  • rpc_methods:"method.name" limits a field to specific RPC methods.
  • rpc_sensitive:"true" marks a field as unsafe for argv transport.

Tagged RPC param fields currently support only bool and string. Positional params must be strings. Adding a tagged int, slice, map, or struct field is a registration-time contract error until the bridge explicitly supports that kind.

RPC params are decoded strictly: unknown JSON fields and trailing JSON values are rejected. The host and plugin also use a lockstep RPC protocol version, so adding even an optional params field requires a coordinated sitectl and plugin rebuild rather than relying on JSON's usual additive compatibility.

Registered plugin commands must declare every bridged flag. Registration validates that contract and panics during startup when a command is missing a required flag, so plugin authors see the mismatch before handling RPC calls. When adding a bridged flag or positional, update the params struct JSON and rpc_* tags, the matching Cobra flag or positional handling, the mirror comment that names the paired command, and the RPC extraction/round-trip tests in cmd/rpc_params_test.go and pkg/plugin/rpc_command_test.go.

Current method-to-argv bridge map: 

| Method | Params | Cobra argv contract |
| --- | --- | --- |
| plugin.metadata | none | no command argv |
| project.detect | ProjectDetectParams | JSON-only path |
| create.component_definitions | none | no command argv |
| create.run | CreateRunParams | create name plus Args |
| deploy.run | DeployRunParams | deploy hook plus Args |
| job.list | none | no command argv |
| job.run | JobRunParams | job name plus Args |
| component.list | ComponentListParams | list subcommand plus optional component name |
| component.describe | ComponentTargetParams | describe plus --component, --path, --codebase-rootfs/--drupal-rootfs, --verbose, --format, plus Args |
| component.reconcile | ComponentTargetParams | reconcile plus --component, --path, --codebase-rootfs/--drupal-rootfs, --report, --verbose, --format, --yolo, plus Args |
| component.set | ComponentSetParams | set plus name/disposition positionals, --path, --state, --disposition, --yolo, plus Args for non-secret follow-up flags |
| validate.run | ValidateRunParams | --codebase-rootfs/--drupal-rootfs plus Args |
| debug.run | DebugRunParams | --verbose plus Args |
| set.run | SetRunParams | --path plus Args |
| converge.run | ConvergeRunParams | --path, --codebase-rootfs/--drupal-rootfs, --report, --verbose, --format, plus Args |

Component RPC is the most common bridged case. ComponentTargetParams.Name is tagged rpc_flags:"component", so the component describe command must declare --component. ComponentTargetParams.CodebaseRootfs is tagged rpc_flags:"codebase-rootfs,drupal-rootfs" and rpc_rootfs:"true", so the paired command must declare those aliases and mark the canonical rootfs flag. ComponentTargetParams.Report is limited to rpc_methods:"component.reconcile", so only the reconcile command declares --report. ComponentSetParams.Name and Disposition are tagged rpc_pos:"0" and rpc_pos:"1", so the component set command receives them as positionals before passthrough args.

Command handlers must write through cmd.OutOrStdout() and cmd.ErrOrStderr(). Direct process writes such as fmt.Println can corrupt the JSON RPC envelope. The host has a best-effort fallback that can recover a valid envelope from the last stdout line, but plugins must not depend on that fallback as a supported transport. RPC dispatch is also single-shot per plugin process; it mutates SDK config and Cobra command state while handling exactly one request.

Index

Constants

View Source 
const (
	// RPCProtocolVersion is the host/plugin JSON protocol version.
	//
	// The RPC protocol is intentionally strict lockstep, not negotiated: a
	// missing version (0) is treated as the current version for callers that
	// predate the explicit field, and any non-current explicit version is
	// rejected. Bumping this value requires rebuilding compatible host and
	// plugin binaries together.
	RPCProtocolVersion = 1

	// MethodPluginMetadata requests plugin capability metadata.
	MethodPluginMetadata = "plugin.metadata"
	// MethodProjectDetect asks a plugin to claim a local project directory.
	MethodProjectDetect = "project.detect"
	// MethodCreateRun runs a registered create definition.
	MethodCreateRun = "create.run"
	// MethodCreateComponentDefinitions lists create definitions exposed by components.
	MethodCreateComponentDefinitions = "create.component_definitions"
	// MethodDeployRun runs a registered deploy hook.
	MethodDeployRun = "deploy.run"
	// MethodJobList lists registered plugin jobs.
	MethodJobList = "job.list"
	// MethodJobRun runs one registered plugin job.
	MethodJobRun = "job.run"
	// MethodComponentList lists plugin component definitions.
	MethodComponentList = "component.list"
	// MethodComponentDescribe describes plugin component state.
	MethodComponentDescribe = "component.describe"
	// MethodComponentReconcile reconciles plugin component defaults.
	MethodComponentReconcile = "component.reconcile"
	// MethodComponentSet applies one plugin component state change.
	MethodComponentSet = "component.set"
	// MethodValidateRun runs plugin validators.
	MethodValidateRun = "validate.run"
	// MethodHealthcheckRun runs plugin health checks.
	MethodHealthcheckRun = "healthcheck.run"
	// MethodDebugRun renders plugin debug sections.
	MethodDebugRun = "debug.run"
	// MethodSetRun runs the plugin-level set handler.
	MethodSetRun = "set.run"
	// MethodConvergeRun runs the plugin-level converge handler.
	MethodConvergeRun = "converge.run"
)
View Source 
const (
	// RPCErrorCodePluginError is the generic code for handler failures.
	RPCErrorCodePluginError = "plugin_error"
	// RPCErrorCodeDecodeRequest means the request envelope could not be decoded.
	RPCErrorCodeDecodeRequest = "decode_request"
	// RPCErrorCodeDecodeParams means method params could not be decoded.
	RPCErrorCodeDecodeParams = "decode_params"
	// RPCErrorCodeUnsupportedMethod means the plugin does not know the method.
	RPCErrorCodeUnsupportedMethod = "unsupported_method"
	// RPCErrorCodeNotRegistered means the plugin did not register that capability.
	RPCErrorCodeNotRegistered = "not_registered"
)

Variables

This section is empty.

Functions

func AddStandardComposeCommands added in v0.16.5 

func AddStandardComposeCommands(s *SDK, opts StandardComposeCommandOptions)

AddStandardComposeCommands registers standard lifecycle, status, logs, and rollout commands for a Docker Compose-backed plugin.

func CloneTemplateRepo added in v0.5.0 

func CloneTemplateRepo(opts GitTemplateOptions) error

func ConfigureTemplateRemotes added in v0.5.0 

func ConfigureTemplateRemotes(opts GitTemplateOptions) error

func ContextPluginSupports added in v0.11.0 

func ContextPluginSupports(contextPlugin, requestedPlugin string) bool

func DecodeRPCParams added in v0.18.0 

func DecodeRPCParams[T any](raw json.RawMessage) (T, error)

DecodeRPCParams unmarshals a structured method-specific params payload.

The wire contract is strict: unknown fields and trailing JSON values are rejected for both stdin and argv RPC transports.

func DecodeRPCResult added in v0.18.0 

func DecodeRPCResult[T any](resp RPCResponse) (T, error)

DecodeRPCResult unmarshals the structured result payload from an RPC response into the requested Go type.

func DetectProjectOwner added in v0.17.0 

func DetectProjectOwner(projectDir, requestedPlugin string) (*config.ProjectClaim, error)

func DockerComposeExecCommand added in v0.16.5 

func DockerComposeExecCommand(service string, args ...string) string

DockerComposeExecCommand builds a shell-safe "docker compose exec -T" command for a service and argv-style command.

func ExtractRPCParamsFromArgs added in v0.18.0 

func ExtractRPCParamsFromArgs[T any](args []string) (T, []string, error)

ExtractRPCParamsFromArgs promotes tagged RPC flags and positionals from args into a typed params struct, returning all unclaimed args as passthrough. Tagged fields currently support bool and string only; rpc_pos fields must be strings.

func InvalidateInstalledDiscoveryCache added in v0.18.0 

func InvalidateInstalledDiscoveryCache()

InvalidateInstalledDiscoveryCache clears process-local plugin discovery results so subsequent discovery sees PATH and plugin metadata changes.

func IsRPCErrorCode added in v0.18.0 

func IsRPCErrorCode(err error, code string) bool

IsRPCErrorCode reports whether err is an RPCFailure with the given code.

func MarkCodebaseRootfsFlag added in v0.18.0 

func MarkCodebaseRootfsFlag(cmd *cobra.Command, flagName string)

MarkCodebaseRootfsFlag marks flagName as the command flag that should receive CodebaseRootfs RPC params when reconstructing argv for a plugin command.

func PrintComposeTemplateCreateSummary added in v0.16.5 

func PrintComposeTemplateCreateSummary(out io.Writer, ctx *config.Context, readyMessage string, setupOnly bool)

PrintComposeTemplateCreateSummary renders the standard create completion summary for compose-template plugins.

func RPCParams added in v0.18.0 

func RPCParams(v any) (json.RawMessage, error)

RPCParams marshals a typed parameter value into a request payload. Prefer the typed New*Request builders when creating requests. Interactive argv transport validates manually attached params against the known method schema, and rejects params that cannot be proven safe for process listings.

func RegisterComposeTemplateCreateRunner added in v0.16.5 

func RegisterComposeTemplateCreateRunner(s *SDK, spec CreateSpec, opts ComposeTemplateCreateOptions)

RegisterComposeTemplateCreateRunner registers the SDK's standard Docker Compose template create runner for a plugin.

func RegisterServiceComponents deprecated added in v0.18.0 

func RegisterServiceComponents(s *SDK, opts ServiceComponentRegistryOptions)

RegisterServiceComponents registers service components on the provided SDK when the SDK is non-nil.

Deprecated: call s.RegisterServiceComponents(opts) when an SDK is already available. This helper remains for existing plugin packages.

func RegisterStandardComposeTemplate added in v0.16.5 

func RegisterStandardComposeTemplate(s *SDK, spec CreateSpec, opts StandardComposeTemplateOptions)

RegisterStandardComposeTemplate registers the standard create flow and lifecycle commands for a Docker Compose template plugin.

func ShellJoin added in v0.16.5 

func ShellJoin(args []string) string

ShellJoin shell-quotes and joins argv-style command arguments.

func ShellQuote added in v0.16.5 

func ShellQuote(value string) string

ShellQuote quotes a value for POSIX shell command construction.

Types

type CheckoutSource added in v0.15.0 

type CheckoutSource string
const (
	CheckoutSourceTemplate CheckoutSource = "template"
	CheckoutSourceExisting CheckoutSource = "existing"
)

type CommandExecOptions added in v0.11.0 

type CommandExecOptions struct {
	Context context.Context
	// Stdin preserves interactive stdin for the plugin. Setting it moves the
	// RPC request envelope to argv. Params marked sensitive are rejected, but
	// request args are not machine-checked and must not contain secrets.
	Stdin      io.Reader
	Stderr     io.Writer
	LiveStderr bool
	LiveStdout bool
}

CommandExecOptions controls subprocess execution for plugin RPC calls. Stdout is always captured into RPCResponse.Output. LiveStdout mirrors command stdout to the plugin process stderr while still capturing it, because process stdout is reserved for the final RPC response envelope. Use Stdin only for interactive RPC methods; when Stdin is nil the host sends the RPC envelope over stdin instead of argv. When Stdin is set, the request is encoded into argv so request args and params may be visible in process listings; never put secrets in any RPCRequest field. The argv safety gate validates typed Params only; Args, Context, and LogLevel are copied as caller-provided values.

type ComponentListParams added in v0.18.0 

type ComponentListParams struct {
	Name string `json:"name,omitempty"`
}

ComponentListParams is the params payload for MethodComponentList.

type ComponentSetParams added in v0.18.0 

type ComponentSetParams struct {
	Name string `json:"name,omitempty" rpc_pos:"0"`
	// Disposition is the positional disposition/state value and is mutually
	// exclusive with DispositionFlag.
	Disposition string `json:"disposition,omitempty" rpc_pos:"1"`
	Path        string `json:"path,omitempty" rpc_flags:"path"`
	State       string `json:"state,omitempty" rpc_flags:"state"`
	// DispositionFlag is the --disposition value and is mutually exclusive
	// with Disposition.
	DispositionFlag string `json:"disposition_flag,omitempty" rpc_flags:"disposition"`
	Yolo            bool   `json:"yolo,omitempty" rpc_flags:"yolo"`
}

ComponentSetParams is the params payload for MethodComponentSet.

The rpc_* tags are the host/plugin argv bridge contract. Keep these fields in lockstep with serviceComponentRegistry.setCommand flags and positionals; RegisterComponentCommand validates the mirrored flag names and value types at plugin startup.

type ComponentTargetParams added in v0.18.0 

type ComponentTargetParams struct {
	Name           string `json:"name,omitempty" rpc_flags:"component"`
	Path           string `json:"path,omitempty" rpc_flags:"path"`
	CodebaseRootfs string `json:"codebase_rootfs,omitempty" rpc_flags:"codebase-rootfs,drupal-rootfs" rpc_rootfs:"true"`
	Report         bool   `json:"report,omitempty" rpc_flags:"report" rpc_methods:"component.reconcile"`
	Verbose        bool   `json:"verbose,omitempty" rpc_flags:"verbose"`
	Format         string `json:"format,omitempty" rpc_flags:"format"`
	Yolo           bool   `json:"yolo,omitempty" rpc_flags:"yolo" rpc_methods:"component.reconcile"`
}

ComponentTargetParams is the params payload for component describe and reconcile RPC methods.

The rpc_* tags are the host/plugin argv bridge contract. Keep these fields in lockstep with serviceComponentRegistry.describeCommand and serviceComponentRegistry.reconcileCommand flags; RegisterComponentCommand validates the mirrored flag names and value types at plugin startup.

type ComposeCreateContextOptions added in v0.15.0 

type ComposeCreateContextOptions struct {
	DefaultName                   string
	DefaultSite                   string
	DefaultPlugin                 string
	DefaultProjectDir             string
	DefaultProjectName            string
	DefaultEnvironment            string
	DefaultDockerSocket           string
	DefaultDatabaseService        string
	DefaultDatabaseUser           string
	DefaultDatabasePasswordSecret string
	DefaultDatabaseName           string
	DefaultDrupalRootfs           string
	DrupalContainerRoot           string
	ConfirmOverwrite              bool
	Input                         config.InputFunc
}

type ComposeCreateRequest added in v0.15.0 

type ComposeCreateRequest struct {
	ContextName        string
	TargetType         config.ContextType
	CheckoutSource     CheckoutSource
	Path               string
	TemplateRepo       string
	TemplateBranch     string
	Site               string
	Environment        string
	ProjectName        string
	ComposeProjectName string
	ComposeNetwork     string
	DockerSocket       string
	SSHHostname        string
	SSHUser            string
	SSHPort            uint
	SSHKeyPath         string
	DrupalRootfs       string
	SetDefaultContext  bool
	SetupOnly          bool
	Decisions          map[string]corecomponent.ReviewDecision
}

type ComposeProjectDiscovery added in v0.17.0 

type ComposeProjectDiscovery struct {
	RequiredServices          []string
	ForbiddenServices         []string
	RequiredComposerPackages  []string
	ForbiddenComposerPackages []string
	ComposerFiles             []string
	Reason                    string
}

type ComposeRemoteContextOptions added in v0.15.0 

type ComposeRemoteContextOptions struct {
	ContextName         string
	DefaultName         string
	Site                string
	DefaultSite         string
	Plugin              string
	ProjectDir          string
	DefaultProjectDir   string
	ProjectName         string
	DefaultProjectName  string
	Environment         string
	DefaultEnvironment  string
	ComposeProjectName  string
	ComposeNetwork      string
	DockerSocket        string
	DatabaseService     string
	DatabaseUser        string
	DatabaseSecret      string
	DatabaseName        string
	SSHHostname         string
	SSHUser             string
	SSHPort             uint
	SSHKeyPath          string
	SetDefault          bool
	ConfirmOverwrite    bool
	Input               config.InputFunc
	DrupalRootfs        string
	DrupalContainerRoot string
}

type ComposeTemplateCreateOptions added in v0.16.5 

type ComposeTemplateCreateOptions struct {
	DefaultPath                   string
	DefaultPlugin                 string
	DefaultEnvironment            string
	DefaultDatabaseService        string
	DefaultDatabaseUser           string
	DefaultDatabasePasswordSecret string
	DefaultDatabaseName           string
	DefaultDrupalRootfs           string
	DrupalContainerRoot           string
	ConfirmOverwrite              bool
	ReadyMessage                  string
	Input                         config.InputFunc
}

ComposeTemplateCreateOptions configures the SDK's standard Docker Compose template create runner.

type Config 

type Config struct {
	LogLevel string
	Context  string
	APIUrl   string
	Format   string
}

Config holds common plugin configuration.

type ContextJob added in v0.13.0 

type ContextJob interface {
	BindFlags(cmd *cobra.Command)
	Run(cmd *cobra.Command, ctx *config.Context) error
}

type ConvergeRunParams added in v0.18.0 

type ConvergeRunParams struct {
	Path           string `json:"path,omitempty" rpc_flags:"path"`
	CodebaseRootfs string `json:"codebase_rootfs,omitempty" rpc_flags:"codebase-rootfs,drupal-rootfs" rpc_rootfs:"true"`
	Report         bool   `json:"report,omitempty" rpc_flags:"report"`
	Verbose        bool   `json:"verbose,omitempty" rpc_flags:"verbose"`
	Format         string `json:"format,omitempty" rpc_flags:"format"`
}

ConvergeRunParams is the params payload for MethodConvergeRun.

type ConvergeRunner added in v0.16.0 

type ConvergeRunner interface {
	BindFlags(cmd *cobra.Command)
	Run(cmd *cobra.Command, ctx *config.Context) error
}

ConvergeRunner implements plugin-specific component convergence. Run detects and repairs configuration drift for the active context.

type CreateRunParams added in v0.18.0 

type CreateRunParams struct {
	Name string `json:"name"`
}

CreateRunParams is the params payload for MethodCreateRun.

type CreateRunner added in v0.14.0 

type CreateRunner interface {
	BindFlags(cmd *cobra.Command)
	Run(cmd *cobra.Command) error
}

type CreateSpec added in v0.14.0 

type CreateSpec struct {
	Name                 string   `json:"name" yaml:"name"`
	Plugin               string   `json:"plugin,omitempty" yaml:"plugin,omitempty"`
	Description          string   `json:"description,omitempty" yaml:"description,omitempty"`
	Default              bool     `json:"default,omitempty" yaml:"default,omitempty"`
	MinCPUCores          float64  `json:"min_cpu_cores,omitempty" yaml:"min_cpu_cores,omitempty"`
	MinMemory            string   `json:"min_memory,omitempty" yaml:"min_memory,omitempty"`
	MinDiskSpace         string   `json:"min_disk_space,omitempty" yaml:"min_disk_space,omitempty"`
	DockerComposeRepo    string   `json:"docker_compose_repo,omitempty" yaml:"docker_compose_repo,omitempty"`
	DockerComposeBranch  string   `json:"docker_compose_branch,omitempty" yaml:"docker_compose_branch,omitempty"`
	DockerComposeBuild   []string `json:"docker_compose_build,omitempty" yaml:"docker_compose_build,omitempty"`
	DockerComposeInit    []string `json:"docker_compose_init,omitempty" yaml:"docker_compose_init,omitempty"`
	DockerComposeUp      []string `json:"docker_compose_up,omitempty" yaml:"docker_compose_up,omitempty"`
	DockerComposeDown    []string `json:"docker_compose_down,omitempty" yaml:"docker_compose_down,omitempty"`
	DockerComposeRollout []string `json:"docker_compose_rollout,omitempty" yaml:"docker_compose_rollout,omitempty"`
}

type DebugRunParams added in v0.18.0 

type DebugRunParams struct {
	Verbose bool `json:"verbose,omitempty" rpc_flags:"verbose"`
}

DebugRunParams is the params payload for MethodDebugRun.

type DebugRunner added in v0.16.0 

type DebugRunner interface {
	BindFlags(cmd *cobra.Command)
	Render(cmd *cobra.Command, ctx *config.Context) (string, error)
}

DebugRunner renders plugin-specific debug diagnostics. Render returns the body content (without panel wrapper) for the plugin's debug section. The SDK wraps the body in a named panel and delegates to included plugins.

type DeployRunParams added in v0.18.0 

type DeployRunParams struct {
	Hook string `json:"hook"`
}

DeployRunParams is the params payload for MethodDeployRun.

type DeployRunner added in v0.16.0 

type DeployRunner interface {
	BindFlags(cmd *cobra.Command)
	PreDown(cmd *cobra.Command, ctx *config.Context) error
	PostUp(cmd *cobra.Command, ctx *config.Context) error
}

DeployRunner implements plugin-specific lifecycle hooks for the deploy flow. PreDown runs before compose down; PostUp runs after compose up.

type DeploySpec added in v0.16.0 

type DeploySpec struct {
	Name        string `json:"name" yaml:"name"`
	Plugin      string `json:"plugin,omitempty" yaml:"plugin,omitempty"`
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	Default     bool   `json:"default,omitempty" yaml:"default,omitempty"`
}

DeploySpec describes a plugin's deploy capability.

type FileAccessor added in v0.12.0 

type FileAccessor struct {
	// contains filtered or unexported fields
}

func NewFileAccessor added in v0.12.0 

func NewFileAccessor(ctx *config.Context) (*FileAccessor, error)

func NewFileAccessorWithSSH added in v0.12.0 

func NewFileAccessorWithSSH(ctx *config.Context, client *ssh.Client, ownsSSH bool) (*FileAccessor, error)

func (*FileAccessor) Close added in v0.12.0 

func (a *FileAccessor) Close() error

func (*FileAccessor) ListFiles added in v0.12.0 

func (a *FileAccessor) ListFiles(root string) ([]string, error)

func (*FileAccessor) MatchFiles added in v0.12.0 

func (a *FileAccessor) MatchFiles(root, pattern string) ([]string, error)

func (*FileAccessor) MatchFilesInDir added in v0.12.0 

func (a *FileAccessor) MatchFilesInDir(root, pattern string) ([]string, error)

func (*FileAccessor) ReadFile added in v0.12.0 

func (a *FileAccessor) ReadFile(path string) ([]byte, error)

func (*FileAccessor) ReadFileContext added in v0.12.0 

func (a *FileAccessor) ReadFileContext(ctx context.Context, path string) ([]byte, error)

func (*FileAccessor) ReadFiles added in v0.12.0 

func (a *FileAccessor) ReadFiles(paths []string) (map[string][]byte, error)

func (*FileAccessor) ReadFilesContext added in v0.12.0 

func (a *FileAccessor) ReadFilesContext(ctx context.Context, paths []string) (map[string][]byte, error)

type GitTemplateOptions added in v0.5.0 

type GitTemplateOptions struct {
	TemplateRepo       string
	TemplateBranch     string
	ProjectDir         string
	GitRemoteURL       string
	GitRemoteName      string
	TemplateRemoteName string
	Quiet              bool
}

type HealthcheckRunParams added in v0.19.0 

type HealthcheckRunParams struct{}

HealthcheckRunParams is the params payload for MethodHealthcheckRun.

type HealthcheckRunner added in v0.19.0 

type HealthcheckRunner interface {
	BindFlags(cmd *cobra.Command)
	Run(cmd *cobra.Command, ctx *config.Context) ([]sitevalidate.Result, error)
}

HealthcheckRunner implements plugin-specific runtime health checks. Run returns a list of healthcheck results for the active context. Diagnostics that should be visible to users should be written to cmd.ErrOrStderr(); stdout is captured by the RPC envelope and may not be displayed by callers.

type InstalledPlugin added in v0.10.0 

type InstalledPlugin struct {
	ProtocolVersion   int          `json:"protocol_version,omitempty" yaml:"protocol_version,omitempty"`
	Name              string       `json:"name" yaml:"name"`
	BinaryName        string       `json:"binary_name,omitempty" yaml:"binary_name,omitempty"`
	Path              string       `json:"path,omitempty" yaml:"path,omitempty"`
	Version           string       `json:"version,omitempty" yaml:"version,omitempty"`
	Description       string       `json:"description,omitempty" yaml:"description,omitempty"`
	Author            string       `json:"author,omitempty" yaml:"author,omitempty"`
	TemplateRepo      string       `json:"template_repo,omitempty" yaml:"template_repo,omitempty"`
	CanCreate         bool         `json:"can_create,omitempty" yaml:"can_create,omitempty"`
	CanDeploy         bool         `json:"can_deploy,omitempty" yaml:"can_deploy,omitempty"`
	CanDebug          bool         `json:"can_debug,omitempty" yaml:"can_debug,omitempty"`
	CanConverge       bool         `json:"can_converge,omitempty" yaml:"can_converge,omitempty"`
	CanSet            bool         `json:"can_set,omitempty" yaml:"can_set,omitempty"`
	CanValidate       bool         `json:"can_validate,omitempty" yaml:"can_validate,omitempty"`
	CanHealthcheck    bool         `json:"can_healthcheck,omitempty" yaml:"can_healthcheck,omitempty"`
	Includes          []string     `json:"includes,omitempty" yaml:"includes,omitempty"`
	CreateDefinitions []CreateSpec `json:"create_definitions,omitempty" yaml:"create_definitions,omitempty"`
	DeployDefinitions []DeploySpec `json:"deploy_definitions,omitempty" yaml:"deploy_definitions,omitempty"`
	MetadataError     string       `json:"metadata_error,omitempty" yaml:"metadata_error,omitempty"`
}

InstalledPlugin is the local registry record for a discovered plugin.

func DiscoverInstalled added in v0.10.0 

func DiscoverInstalled() []InstalledPlugin

func DiscoverInstalledFromPath added in v0.10.0 

func DiscoverInstalledFromPath(pathEnv string) []InstalledPlugin

func DiscoverInstalledLightweight added in v0.15.0 

func DiscoverInstalledLightweight() []InstalledPlugin

func DiscoverInstalledLightweightFromPath added in v0.15.0 

func DiscoverInstalledLightweightFromPath(pathEnv string) []InstalledPlugin

func FindInstalled added in v0.11.0 

func FindInstalled(name string) (InstalledPlugin, bool)

FindInstalled returns metadata for a sitectl plugin discovered on PATH.

Executables named sitectl-* on PATH are treated as trusted plugins; invoking them uses the same trust boundary as running those plugin binaries directly.

type JobRunParams added in v0.18.0 

type JobRunParams struct {
	Name string `json:"name"`
}

JobRunParams is the params payload for MethodJobRun.

type Metadata 

type Metadata struct {
	Name         string
	Version      string
	Description  string
	Author       string
	TemplateRepo string
	Includes     []string
}

Metadata contains information about a plugin

type PluginMetadata added in v0.18.0 

type PluginMetadata struct {
	// ProtocolVersion is the metadata payload version. The RPCResponse envelope
	// carrying this payload has its own protocol_version check.
	ProtocolVersion   int          `json:"protocol_version,omitempty" yaml:"protocol_version,omitempty"`
	Name              string       `json:"name" yaml:"name"`
	BinaryName        string       `json:"binary_name,omitempty" yaml:"binary_name,omitempty"`
	Version           string       `json:"version,omitempty" yaml:"version,omitempty"`
	Description       string       `json:"description,omitempty" yaml:"description,omitempty"`
	Author            string       `json:"author,omitempty" yaml:"author,omitempty"`
	TemplateRepo      string       `json:"template_repo,omitempty" yaml:"template_repo,omitempty"`
	CanCreate         bool         `json:"can_create,omitempty" yaml:"can_create,omitempty"`
	CanDeploy         bool         `json:"can_deploy,omitempty" yaml:"can_deploy,omitempty"`
	CanDebug          bool         `json:"can_debug,omitempty" yaml:"can_debug,omitempty"`
	CanConverge       bool         `json:"can_converge,omitempty" yaml:"can_converge,omitempty"`
	CanSet            bool         `json:"can_set,omitempty" yaml:"can_set,omitempty"`
	CanValidate       bool         `json:"can_validate,omitempty" yaml:"can_validate,omitempty"`
	CanHealthcheck    bool         `json:"can_healthcheck,omitempty" yaml:"can_healthcheck,omitempty"`
	Includes          []string     `json:"includes,omitempty" yaml:"includes,omitempty"`
	CreateDefinitions []CreateSpec `json:"create_definitions,omitempty" yaml:"create_definitions,omitempty"`
	DeployDefinitions []DeploySpec `json:"deploy_definitions,omitempty" yaml:"deploy_definitions,omitempty"`
}

PluginMetadata is the JSON metadata payload returned by plugin.metadata RPC.

type ProgressLine added in v0.13.0 

type ProgressLine struct {
	// contains filtered or unexported fields
}

ProgressLine renders a transient single-line progress indicator on terminals.

func NewProgressLine added in v0.13.0 

func NewProgressLine(w io.Writer, title, detail string) *ProgressLine

NewProgressLine starts a single-line terminal progress indicator.

func (*ProgressLine) Close added in v0.13.0 

func (p *ProgressLine) Close()

Close stops the progress indicator and clears its line.

func (*ProgressLine) Report added in v0.13.0 

func (p *ProgressLine) Report(title, detail string)

Report updates the progress line text.

type ProjectDetectParams added in v0.18.0 

type ProjectDetectParams struct {
	Path string `json:"path"`
}

ProjectDetectParams is the params payload for MethodProjectDetect.

type ProjectDiscoveryFunc added in v0.17.0 

type ProjectDiscoveryFunc func(projectDir string) (*config.ProjectClaim, error)

type RPCError added in v0.18.0 

type RPCError struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

RPCError is the structured failure payload returned by plugin RPC handlers. Code is an open vocabulary: RPCErrorCode* values are reserved for core sitectl protocol and dispatch failures, and plugins may return their own domain-specific codes for callers that know how to interpret them.

type RPCFailure added in v0.18.0 

type RPCFailure struct {
	Plugin  string
	Method  string
	Code    string
	Message string
	Output  string
	Err     error
}

RPCFailure is returned by InvokePluginRPC when the plugin returns a valid RPC error envelope. Code may be one of the core-reserved RPCErrorCode* constants or a plugin-defined value; use IsRPCErrorCode to branch only on codes your caller understands.

func (*RPCFailure) Error added in v0.18.0 

func (e *RPCFailure) Error() string

Error returns the plugin-provided RPC error message.

func (*RPCFailure) Unwrap added in v0.18.0 

func (e *RPCFailure) Unwrap() error

Unwrap returns the wrapped process or protocol error, when one exists.

type RPCProcessError added in v0.18.0 

type RPCProcessError struct {
	Plugin   string
	Method   string
	ExitCode int
	Detail   string
	Err      error
}

RPCProcessError reports a plugin subprocess failure before a valid RPC response envelope was returned.

func (*RPCProcessError) Error added in v0.18.0 

func (e *RPCProcessError) Error() string

Error formats the process failure with any captured stderr/stdout detail.

func (*RPCProcessError) Unwrap added in v0.18.0 

func (e *RPCProcessError) Unwrap() error

Unwrap returns the underlying exec error.

type RPCRequest added in v0.18.0 

type RPCRequest struct {
	ProtocolVersion int    `json:"protocol_version"`
	Method          string `json:"method"`
	Context         string `json:"context,omitempty"`
	LogLevel        string `json:"log_level,omitempty"`
	// Args is method-specific passthrough argv. Interactive RPC calls that set
	// CommandExecOptions.Stdin send the whole request through argv, so args and
	// params may be visible in process listings. Args are caller-trusted and are
	// not covered by params sensitivity checks; never put secrets in Args.
	Args []string `json:"args,omitempty"`
	// Params is method-specific JSON. Interactive RPC calls that set
	// CommandExecOptions.Stdin send the whole request through argv, so args and
	// params may be visible in process listings. Never put secrets in Params.
	Params json.RawMessage `json:"params,omitempty"`
	// contains filtered or unexported fields
}

RPCRequest is the single host-to-plugin request envelope accepted by __sitectl-rpc.

Method is a strict core-owned vocabulary. Plugins expose capabilities by registering handlers for these methods; adding a new RPC method requires a coordinated sitectl and plugin release, not an open-ended plugin extension.

func NewComponentDescribeRequest added in v0.18.0 

func NewComponentDescribeRequest(params ComponentTargetParams, args ...string) (RPCRequest, error)

NewComponentDescribeRequest creates a typed component.describe request.

func NewComponentListRequest added in v0.18.0 

func NewComponentListRequest(name string) (RPCRequest, error)

NewComponentListRequest creates a typed component.list request.

func NewComponentReconcileRequest added in v0.18.0 

func NewComponentReconcileRequest(params ComponentTargetParams, args ...string) (RPCRequest, error)

NewComponentReconcileRequest creates a typed component.reconcile request.

func NewComponentSetRequest added in v0.18.0 

func NewComponentSetRequest(params ComponentSetParams, args ...string) (RPCRequest, error)

NewComponentSetRequest creates a typed component.set request.

func NewConvergeRunRequest added in v0.18.0 

func NewConvergeRunRequest(params ConvergeRunParams, args ...string) (RPCRequest, error)

NewConvergeRunRequest creates a typed converge.run request.

func NewCreateRunRequest added in v0.18.0 

func NewCreateRunRequest(name string, args ...string) (RPCRequest, error)

NewCreateRunRequest creates a typed create.run request.

func NewDebugRunRequest added in v0.18.0 

func NewDebugRunRequest(params DebugRunParams, args ...string) (RPCRequest, error)

NewDebugRunRequest creates a typed debug.run request.

func NewDeployRunRequest added in v0.18.0 

func NewDeployRunRequest(hook string, args ...string) (RPCRequest, error)

NewDeployRunRequest creates a typed deploy.run request.

func NewHealthcheckRunRequest added in v0.19.0 

func NewHealthcheckRunRequest(params HealthcheckRunParams, args ...string) (RPCRequest, error)

NewHealthcheckRunRequest creates a typed healthcheck.run request.

func NewJobRunRequest added in v0.18.0 

func NewJobRunRequest(name string, args ...string) (RPCRequest, error)

NewJobRunRequest creates a typed job.run request.

func NewProjectDetectRequest added in v0.18.0 

func NewProjectDetectRequest(path string) (RPCRequest, error)

NewProjectDetectRequest creates a typed project.detect request.

func NewRPCRequest added in v0.18.0 

func NewRPCRequest(method string) RPCRequest

NewRPCRequest creates a request envelope for a plugin RPC method.

func NewSetRunRequest added in v0.18.0 

func NewSetRunRequest(params SetRunParams, args ...string) (RPCRequest, error)

NewSetRunRequest creates a typed set.run request.

func NewValidateRunRequest added in v0.18.0 

func NewValidateRunRequest(params ValidateRunParams, args ...string) (RPCRequest, error)

NewValidateRunRequest creates a typed validate.run request.

type RPCResponse added in v0.18.0 

type RPCResponse struct {
	ProtocolVersion int             `json:"protocol_version"`
	OK              bool            `json:"ok"`
	Result          json.RawMessage `json:"result,omitempty"`
	Output          string          `json:"output,omitempty"`
	Error           *RPCError       `json:"error,omitempty"`
}

RPCResponse is the single plugin-to-host response envelope emitted by __sitectl-rpc.

type RPCSensitiveParams added in v0.18.0 

type RPCSensitiveParams interface {
	HasSensitiveRPCParams() bool
}

RPCSensitiveParams marks a params value as unsafe for argv transport.

InvokePluginRPC refuses to run interactive calls with Stdin set when the request was built from params that return true here. Implementations may use value or pointer receivers. Only typed Params are screened; never place secrets in Args, Context, or LogLevel. Core RPC params are currently secret-free; this interface and the rpc_sensitive struct tag are kept for future methods that may need secrets.

type RegisteredCreate added in v0.14.0 

type RegisteredCreate struct {
	Spec    CreateSpec
	Command *cobra.Command
}

type RegisteredDeploy added in v0.16.0 

type RegisteredDeploy struct {
	Spec DeploySpec
}

RegisteredDeploy holds a registered deploy spec.

type RegisteredJob added in v0.13.0 

type RegisteredJob struct {
	Spec    job.Spec
	Command *cobra.Command
}

type SDK 

type SDK struct {
	Metadata Metadata
	// Config is updated during normal command setup and single-shot RPC
	// dispatch. Do not treat one SDK value as immutable across RPC requests.
	Config  Config
	RootCmd *cobra.Command
	// contains filtered or unexported fields
}

SDK provides common functionality for plugins.

Command registration and RPC dispatch mutate cobra command state and are not safe to fan out through one SDK concurrently. The SDK guards its context and SSH connection caches so host-side discovery helpers can reuse them safely.

func NewSDK 

func NewSDK(metadata Metadata) *SDK

NewSDK creates a new plugin SDK instance

func (*SDK) AddCommand 

func (s *SDK) AddCommand(cmd *cobra.Command)

AddCommand adds a subcommand to the plugin

func (*SDK) AddStandardComposeCommands added in v0.16.5 

func (s *SDK) AddStandardComposeCommands(opts StandardComposeCommandOptions)

AddStandardComposeCommands registers standard lifecycle, status, logs, and rollout commands for the receiver plugin.

func (*SDK) BindComposeCreateFlags added in v0.15.0 

func (s *SDK) BindComposeCreateFlags(cmd *cobra.Command, spec CreateSpec, drupalRootfs *string, defaultDrupalRootfs string) error

func (*SDK) CloneTemplateRepo added in v0.5.0 

func (s *SDK) CloneTemplateRepo(opts GitTemplateOptions) error

func (*SDK) Close added in v0.12.0 

func (s *SDK) Close() error

func (*SDK) ConfigureTemplateRemotes added in v0.5.0 

func (s *SDK) ConfigureTemplateRemotes(opts GitTemplateOptions) error

func (*SDK) ContextFromCommand added in v0.16.5 

func (s *SDK) ContextFromCommand(cmd *cobra.Command) (*config.Context, error)

ContextFromCommand loads the sitectl context selected by a Cobra command.

func (*SDK) ContextValidators added in v0.9.0 

func (s *SDK) ContextValidators() []validate.Validator

func (*SDK) CreateComponentDefinitions added in v0.15.0 

func (s *SDK) CreateComponentDefinitions() ([]corecomponent.Definition, error)

func (*SDK) CreateDefinitions added in v0.14.0 

func (s *SDK) CreateDefinitions() []CreateSpec

func (*SDK) DeployDefinitions added in v0.16.0 

func (s *SDK) DeployDefinitions() []DeploySpec

DeployDefinitions returns the deploy specs registered with this SDK instance.

func (*SDK) EnsureComposeCreateContext added in v0.15.0 

func (s *SDK) EnsureComposeCreateContext(req ComposeCreateRequest, opts ComposeCreateContextOptions) (*config.Context, error)

func (*SDK) EnsureComposeTemplateCheckout added in v0.16.5 

func (s *SDK) EnsureComposeTemplateCheckout(out io.Writer, req ComposeCreateRequest, ctx *config.Context) (bool, error)

EnsureComposeTemplateCheckout ensures the requested Docker Compose template exists for the target context and returns whether a new checkout was cloned.

func (*SDK) EnsureComposeTemplateCheckoutContext added in v0.17.4 

func (s *SDK) EnsureComposeTemplateCheckoutContext(runCtx context.Context, out io.Writer, req ComposeCreateRequest, ctx *config.Context) (bool, error)

EnsureComposeTemplateCheckoutContext ensures the requested Docker Compose template exists for the target context with cancellation support.

func (*SDK) ExecContainer added in v0.12.0 

func (s *SDK) ExecContainer(ctx context.Context, opts docker.ExecOptions) (int, error)

ExecContainer executes a command in a Docker container using the shared SDK Docker path.

func (*SDK) ExecInContainer 

func (s *SDK) ExecInContainer(ctx context.Context, containerID string, cmd []string) (int, error)

ExecInContainer executes a command in a Docker container. This is a convenience wrapper for plugins.

func (*SDK) ExecInContainerInteractive 

func (s *SDK) ExecInContainerInteractive(ctx context.Context, containerID string, cmd []string) (int, error)

ExecInContainerInteractive executes an interactive command in a Docker container with TTY. This is a convenience wrapper for plugins.

func (*SDK) Execute 

func (s *SDK) Execute()

Execute runs the plugin

func (*SDK) GetComponentManager added in v0.5.0 

func (s *SDK) GetComponentManager() (*component.Manager, error)

GetComponentManager creates a component manager bound to the active sitectl context.

func (*SDK) GetContext 

func (s *SDK) GetContext() (*config.Context, error)

GetContext loads the sitectl context configuration This is useful for plugins that need to access context-specific settings If no context is specified, returns the current context from config

func (*SDK) GetDockerClient 

func (s *SDK) GetDockerClient() (*docker.DockerClient, error)

GetDockerClient creates a Docker client respecting the sitectl context This is a helper for plugins that need to interact with Docker Returns the existing DockerClient which handles both local and remote contexts

func (*SDK) GetFileAccessor added in v0.12.0 

func (s *SDK) GetFileAccessor() (*FileAccessor, error)

func (*SDK) GetRPCCommand added in v0.18.0 

func (s *SDK) GetRPCCommand() *cobra.Command

GetRPCCommand returns the single private host/plugin entrypoint.

The returned command is a single-shot subprocess entrypoint. RPC dispatch mutates SDK config and cobra command state while executing one request; do not reuse it for multiple requests in the same process. Plugin handlers must write user-visible output through cmd.OutOrStdout(); direct os.Stdout writes corrupt the JSON response envelope reserved for host/plugin framing.

Correct handlers use cobra's output stream, for example: 

_, err := fmt.Fprintln(cmd.OutOrStdout(), output)
return err

func (*SDK) GetSSHClient added in v0.12.0 

func (s *SDK) GetSSHClient() (*ssh.Client, error)

GetSSHClient returns an SSH client for the resolved sitectl context.

func (*SDK) InvokeIncludedPluginJob added in v0.18.0 

func (s *SDK) InvokeIncludedPluginJob(pluginName, jobName string, args []string, opts CommandExecOptions) (RPCResponse, error)

InvokeIncludedPluginJob invokes a registered job on an included plugin.

func (*SDK) InvokeIncludedPluginJobContext added in v0.18.0 

func (s *SDK) InvokeIncludedPluginJobContext(pluginName, contextName, jobName string, args []string, opts CommandExecOptions) (RPCResponse, error)

InvokeIncludedPluginJobContext invokes a registered job on an included plugin against a specific sitectl context.

func (*SDK) InvokeIncludedPluginRPC added in v0.18.0 

func (s *SDK) InvokeIncludedPluginRPC(pluginName string, req RPCRequest, opts CommandExecOptions) (RPCResponse, error)

InvokeIncludedPluginRPC invokes a plugin declared in this SDK's Includes metadata through the private RPC entrypoint.

func (*SDK) InvokePluginRPC added in v0.18.0 

func (s *SDK) InvokePluginRPC(pluginName string, req RPCRequest, opts CommandExecOptions) (RPCResponse, error)

InvokePluginRPC invokes an installed sitectl plugin through the private RPC entrypoint and returns the decoded response envelope.

When opts.Stdin is set, the request envelope is encoded into argv so the plugin can keep stdin interactive. Args and params in that mode may be visible in process listings; never put secrets in any RPC field. Requests built from params marked with RPCSensitiveParams or `rpc_sensitive:"true"` are rejected before the subprocess starts; Args, Context, and LogLevel remain caller-trusted and are not inspected by that sensitivity check.

func (*SDK) LocalComponentDefinitions added in v0.15.0 

func (s *SDK) LocalComponentDefinitions() []corecomponent.Definition

func (*SDK) MustRegisterStandardServiceComponentPlugin added in v0.18.0 

func (s *SDK) MustRegisterStandardServiceComponentPlugin(opts StandardServiceComponentPluginOptions)

MustRegisterStandardServiceComponentPlugin is like RegisterStandardServiceComponentPlugin, but panics when component construction fails during plugin startup.

func (*SDK) PromptAndSaveLocalContext added in v0.5.0 

func (s *SDK) PromptAndSaveLocalContext(opts config.LocalContextCreateOptions) (*config.Context, error)

PromptAndSaveLocalContext creates or updates a local sitectl context using the shared config prompts and save behavior.

func (*SDK) RegisterComponentCommand added in v0.18.0 

func (s *SDK) RegisterComponentCommand(cmd *cobra.Command)

RegisterComponentCommand registers a hidden component command tree for RPC dispatch from core sitectl. Registered describe, reconcile, and set subcommands must declare the flags bridged by their typed RPC params; registration panics if a required flag is missing.

func (*SDK) RegisterComponentDefinition added in v0.15.0 

func (s *SDK) RegisterComponentDefinition(def corecomponent.Definition)

func (*SDK) RegisterComponentDefinitions added in v0.15.0 

func (s *SDK) RegisterComponentDefinitions(defs ...corecomponent.Definition)

func (*SDK) RegisterComposeTemplateCreateRunner added in v0.16.5 

func (s *SDK) RegisterComposeTemplateCreateRunner(spec CreateSpec, opts ComposeTemplateCreateOptions)

RegisterComposeTemplateCreateRunner registers the SDK's standard Docker Compose template create runner for the receiver plugin.

func (*SDK) RegisterContextJob added in v0.13.0 

func (s *SDK) RegisterContextJob(spec job.Spec, runner ContextJob)

func (*SDK) RegisterContextValidator added in v0.9.0 

func (s *SDK) RegisterContextValidator(validator validate.Validator)

func (*SDK) RegisterConvergeRunner added in v0.16.0 

func (s *SDK) RegisterConvergeRunner(runner ConvergeRunner)

RegisterConvergeRunner registers a converge runner for the plugin. The SDK invokes it through the plugin RPC entrypoint for sitectl converge. BindFlags must declare the RPC-bridged --path, --codebase-rootfs, --report, --verbose, and --format flags. If BindFlags uses a plugin-specific flag for CodebaseRootfs params, mark it with MarkCodebaseRootfsFlag. Registration panics if required bridge flags are missing.

func (*SDK) RegisterCreate added in v0.14.0 

func (s *SDK) RegisterCreate(spec CreateSpec, cmd *cobra.Command)

func (*SDK) RegisterCreateRunner added in v0.14.0 

func (s *SDK) RegisterCreateRunner(spec CreateSpec, runner CreateRunner)

func (*SDK) RegisterDebugHandler deprecated added in v0.16.0 

func (s *SDK) RegisterDebugHandler(runner DebugRunner)

RegisterDebugHandler registers a debug runner for the plugin.

Deprecated: use RegisterDebugRunner.

func (*SDK) RegisterDebugRunner added in v0.18.0 

func (s *SDK) RegisterDebugRunner(runner DebugRunner)

RegisterDebugRunner registers a debug runner for the plugin. BindFlags must declare the RPC-bridged --verbose flag when the runner accepts core verbose state; registration panics if required bridge flags are missing. The SDK stores the debug handler, wraps the runner's output in a named panel, and delegates to any included plugins through the RPC entrypoint. Render implementations should return their text to the SDK; lower-level command handlers must write with cmd.OutOrStdout(), not fmt.Println.

func (*SDK) RegisterDeployRunner added in v0.16.0 

func (s *SDK) RegisterDeployRunner(spec DeploySpec, runner DeployRunner)

RegisterDeployRunner registers a deploy runner for the plugin. The SDK creates deploy lifecycle methods invoked through the plugin RPC entrypoint around the compose down/up cycle.

func (*SDK) RegisterHealthcheckRunner added in v0.19.0 

func (s *SDK) RegisterHealthcheckRunner(runner HealthcheckRunner)

RegisterHealthcheckRunner registers a healthcheck runner for the plugin. The SDK stores the handler that is invoked through the plugin RPC entrypoint. The handler output is encoded into the RPC result and merged with core health results before writing the final report. If BindFlags uses a plugin-specific flag for CodebaseRootfs params, mark it with MarkCodebaseRootfsFlag.

func (*SDK) RegisterJob added in v0.13.0 

func (s *SDK) RegisterJob(spec job.Spec, cmd *cobra.Command)

func (*SDK) RegisterServiceComponents added in v0.18.0 

func (s *SDK) RegisterServiceComponents(opts ServiceComponentRegistryOptions)

RegisterServiceComponents registers compose-backed service components and their hidden RPC command handlers. It is idempotent for component names: each call adds new components to the SDK's accumulated set, then rebuilds the component command tree from that set.

func (*SDK) RegisterSetRunner added in v0.16.0 

func (s *SDK) RegisterSetRunner(runner SetRunner)

RegisterSetRunner registers a set runner for the plugin. The SDK invokes it through the plugin RPC entrypoint for sitectl set. BindFlags must declare the RPC-bridged --path flag; registration panics if required bridge flags are missing.

func (*SDK) RegisterStandardComposeTemplate added in v0.16.5 

func (s *SDK) RegisterStandardComposeTemplate(spec CreateSpec, opts StandardComposeTemplateOptions)

RegisterStandardComposeTemplate registers the standard create flow and lifecycle commands for the receiver plugin.

func (*SDK) RegisterStandardServiceComponentPlugin added in v0.18.0 

func (s *SDK) RegisterStandardServiceComponentPlugin(opts StandardServiceComponentPluginOptions) error

RegisterStandardServiceComponentPlugin registers compose discovery, create template support, lifecycle commands, and service components for a standard compose-backed service plugin.

func (*SDK) RegisterValidateRunner added in v0.16.0 

func (s *SDK) RegisterValidateRunner(runner ValidateRunner)

RegisterValidateRunner registers a validate runner for the plugin. The SDK stores the validate handler that is invoked through the plugin RPC entrypoint. The handler output is encoded into the RPC result and merged with core validation results before writing the final report. BindFlags must declare the RPC-bridged --codebase-rootfs flag. If BindFlags uses a plugin-specific flag for CodebaseRootfs params, mark it with MarkCodebaseRootfsFlag. Registration panics if required bridge flags are missing.

func (*SDK) ResolveComposeCreateRequest added in v0.15.0 

func (s *SDK) ResolveComposeCreateRequest(cmd *cobra.Command, input config.InputFunc, drupalRootfs, defaultPath, defaultRepo, defaultBranch string) (ComposeCreateRequest, error)

func (*SDK) RunActiveComposeProjectCommand added in v0.16.5 

func (s *SDK) RunActiveComposeProjectCommand(cmd *cobra.Command, command string) error

RunActiveComposeProjectCommand runs a shell command in the active context's compose project directory.

func (*SDK) RunActiveComposeProjectCommandList added in v0.16.5 

func (s *SDK) RunActiveComposeProjectCommandList(cmd *cobra.Command, commands []string) error

RunActiveComposeProjectCommandList runs shell commands in the active context's compose project directory.

func (*SDK) RunComposeProjectCommand added in v0.16.5 

func (s *SDK) RunComposeProjectCommand(ctx *config.Context, projectDir string, stdout, stderr io.Writer, command string) error

RunComposeProjectCommand runs a shell command in a compose project directory, honoring local and remote sitectl contexts.

func (*SDK) RunComposeProjectCommandContext added in v0.17.4 

func (s *SDK) RunComposeProjectCommandContext(runCtx context.Context, ctx *config.Context, projectDir string, stdout, stderr io.Writer, command string) error

RunComposeProjectCommandContext runs a shell command in a compose project directory with cancellation support.

func (*SDK) RunComposeProjectCommandList added in v0.16.5 

func (s *SDK) RunComposeProjectCommandList(cmd *cobra.Command, ctx *config.Context, commands []string) error

RunComposeProjectCommandList runs a list of shell commands in a compose project's directory, skipping empty command strings.

func (*SDK) SetComposeProjectDiscovery added in v0.17.0 

func (s *SDK) SetComposeProjectDiscovery(spec ComposeProjectDiscovery)

func (*SDK) SetProjectDiscovery added in v0.17.0 

func (s *SDK) SetProjectDiscovery(discovery ProjectDiscoveryFunc)

func (*SDK) SetVersionInfo added in v0.6.1 

func (s *SDK) SetVersionInfo(version, commit, date string)

SetVersionInfo formats plugin version metadata like the main sitectl binary.

type ServiceComponentRegistryOptions added in v0.18.0 

type ServiceComponentRegistryOptions struct {
	DisplayName string
	Components  []corecomponent.ComposeServiceComponent
}

ServiceComponentRegistryOptions configures component registration for service plugins backed by compose definitions.

type SetRunParams added in v0.18.0 

type SetRunParams struct {
	Path string `json:"path,omitempty" rpc_flags:"path"`
}

SetRunParams is the params payload for MethodSetRun.

type SetRunner added in v0.16.0 

type SetRunner interface {
	BindFlags(cmd *cobra.Command)
	Run(cmd *cobra.Command, args []string, ctx *config.Context) error
}

SetRunner implements plugin-specific component state management. Run applies the requested state or disposition to the named component.

type StandardComposeCommandOptions added in v0.16.5 

type StandardComposeCommandOptions struct {
	DisplayName     string
	LogsTail        int
	BuildCommands   []string
	InitCommands    []string
	UpCommands      []string
	DownCommands    []string
	RolloutCommands []string
	RolloutCommand  string
}

StandardComposeCommandOptions configures standard Docker Compose helper commands registered by the SDK.

type StandardComposeTemplateOptions added in v0.16.5 

type StandardComposeTemplateOptions struct {
	DefaultPath                   string
	DefaultPlugin                 string
	DefaultEnvironment            string
	DefaultDatabaseService        string
	DefaultDatabaseUser           string
	DefaultDatabasePasswordSecret string
	DefaultDatabaseName           string
	DefaultDrupalRootfs           string
	DrupalContainerRoot           string
	ConfirmOverwrite              bool
	ReadyMessage                  string
	DisplayName                   string
	LogsTail                      int
	Input                         config.InputFunc
}

StandardComposeTemplateOptions configures the SDK's standard Compose template create runner and lifecycle commands from one application spec.

type StandardServiceComponentPluginOptions added in v0.18.0 

type StandardServiceComponentPluginOptions struct {
	PluginName       string
	DisplayName      string
	DefaultPath      string
	RequiredServices []string
	DiscoveryReason  string
	ReadyMessage     string
	CreateSpec       CreateSpec
	Components       func() ([]corecomponent.ComposeServiceComponent, error)
}

StandardServiceComponentPluginOptions configures the common registration shape for compose-backed service plugins.

type ValidateRunParams added in v0.18.0 

type ValidateRunParams struct {
	CodebaseRootfs string `json:"codebase_rootfs,omitempty" rpc_flags:"codebase-rootfs,drupal-rootfs" rpc_rootfs:"true"`
}

ValidateRunParams is the params payload for MethodValidateRun.

type ValidateRunner added in v0.16.0 

type ValidateRunner interface {
	BindFlags(cmd *cobra.Command)
	Run(cmd *cobra.Command, ctx *config.Context) ([]sitevalidate.Result, error)
}

ValidateRunner implements plugin-specific context validation. Run returns a list of validation results for the active context. Diagnostics that should be visible to users should be written to cmd.ErrOrStderr(); stdout is captured by the RPC envelope and may not be displayed by callers.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.