extension

package
v1.0.48340 Latest Latest
Warning

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

Go to latest
Published: Aug 18, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source
const ReferenceAnnotation = "extension:reference"

ReferenceAnnotation is the cobra command annotation key for when an extension provides reference documentation.

Variables

This section is empty.

Functions

This section is empty.

Types

type Binary

type Binary struct {
	Path   string `json:"name"`
	Arch   string `json:"arch"`
	Sys    string `json:"sys"`
	Sha256 string `json:"sha256"`
}

type Config

type Config struct {
	Version string
	Agent   string
	BaseURL string
}

type ErrChecksumMismatch

type ErrChecksumMismatch struct {
	Expected string
	Got      string
}

ErrChecksumMismatch is returned when the downloaded binary does not match the expected SHA256.

func (*ErrChecksumMismatch) Error

func (e *ErrChecksumMismatch) Error() string

type ErrCorruptExtensionManifest

type ErrCorruptExtensionManifest struct {
	ManifestPath string
	Err          error
}

func (*ErrCorruptExtensionManifest) Error

type ErrDownloadFailed

type ErrDownloadFailed struct {
	StatusCode int
}

ErrDownloadFailed is returned when the binary download returns a non-200 status.

func (*ErrDownloadFailed) Error

func (e *ErrDownloadFailed) Error() string

type ErrExited

type ErrExited struct {
	Code int
}

ErrExited is returned by Run when the extension process exits with a non-zero status code. The caller should exit with Code rather than printing an error message — the extension is responsible for its own error output.

func (*ErrExited) Error

func (e *ErrExited) Error() string

type ErrExtensionBinaryNotFound

type ErrExtensionBinaryNotFound struct {
	Name string
	Path string
}

ErrExtensionBinaryNotFound is returned when the extension binary named in a manifest does not exist on disk

func (*ErrExtensionBinaryNotFound) Error

type ErrExtensionNotFound

type ErrExtensionNotFound struct {
	Name string
}

ErrExtensionNotFound is returned when the extension does not exist in the registry.

func (*ErrExtensionNotFound) Error

func (e *ErrExtensionNotFound) Error() string

type ErrExtensionNotInstalled

type ErrExtensionNotInstalled struct {
	Name string
}

ErrExtensionNotInstalled is returned when attempting to remove an extension that is not installed.

func (*ErrExtensionNotInstalled) Error

func (e *ErrExtensionNotInstalled) Error() string

type ErrExtensionTooLarge

type ErrExtensionTooLarge struct {
	Name    string
	MaxSize int64
}

ErrExtensionTooLarge is returned when the decompressed extension binary exceeds the maximum allowed size.

func (*ErrExtensionTooLarge) Error

func (e *ErrExtensionTooLarge) Error() string

type ErrInvalidName

type ErrInvalidName struct {
	Name string
}

ErrInvalidName is returned when the extension name contains invalid characters.

func (*ErrInvalidName) Error

func (e *ErrInvalidName) Error() string

type ErrNoBinaryForPlatform

type ErrNoBinaryForPlatform struct {
	Name string
	OS   string
	Arch string
}

ErrNoBinaryForPlatform is returned when the registry has no binary for the current OS/arch.

func (*ErrNoBinaryForPlatform) Error

func (e *ErrNoBinaryForPlatform) Error() string

type Extension

type Extension struct {
	BinaryName string
	Version    string
	Arch       string
	Sys        string
	Sha256     string
	URL        string
	Ref        *Reference
}

type LatestData

type LatestData struct {
	Version  string     `json:"version"`
	Binaries []Binary   `json:"binaries"`
	Ref      *Reference `json:"reference,omitempty"`
}

type Manager

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

func NewManager

func NewManager(cfg Config) *Manager

func (*Manager) Download

func (m *Manager) Download(ctx context.Context, ext Extension) (io.ReadCloser, error)

func (*Manager) Get

func (m *Manager) Get(ctx context.Context, binaryName string) (Extension, error)

type Manifest

type Manifest struct {
	Name       string     `yaml:"name"`
	BinaryName string     `yaml:"binary_name"`
	Version    string     `yaml:"version"`
	Sha256     string     `yaml:"sha256"`
	URL        string     `yaml:"url"`
	Path       string     `yaml:"path"`
	Ref        *Reference `yaml:"reference,omitempty"`
}

func (*Manifest) Run

func (ext *Manifest) Run(ctx context.Context, client *apiclient.Client, args []string) error

Run executes the extension binary with args, injecting CircleCI environment variables.

The current process is replaced by the extension via syscall exec on Unix; on Windows the extension is run as a child process and its exit code is propagated.

If the extension binary is not found, ErrExtensionBinaryNotFound is returned and the caller should show prompt the user to reinstall the extension.

type Reference

type Reference struct {
	Use         string          `json:"use,omitempty" yaml:"use,omitempty"`
	Short       string          `json:"short,omitempty" yaml:"short,omitempty"`
	Long        string          `json:"long,omitempty" yaml:"long,omitempty"`
	Args        []ReferenceArg  `json:"args,omitempty" yaml:"args,omitempty"`
	Flags       []ReferenceFlag `json:"flags,omitempty" yaml:"flags,omitempty"`
	Subcommands []ReferenceSub  `json:"subcommands,omitempty" yaml:"subcommands,omitempty"`
}

Reference describes an extension command and, recursively, its subcommands. It is owned by the extension and fetched from the extension registry's release.json. When present, it enriches the CLI's generated reference docs; when absent, the CLI falls back to the base extension docs.

type ReferenceArg

type ReferenceArg struct {
	Name string `json:"name" yaml:"name"`
	Help string `json:"help,omitempty" yaml:"help,omitempty"`
}

ReferenceArg describes a single argument for Reference.

type ReferenceFlag

type ReferenceFlag struct {
	Name      string `json:"name" yaml:"name"`
	Shorthand string `json:"shorthand,omitempty" yaml:"shorthand,omitempty"`
	Usage     string `json:"usage,omitempty" yaml:"usage,omitempty"`
	// Type is the value placeholder shown after the flag name, e.g. "string".
	// Empty means the flag takes no value (boolean-style).
	Type    string `json:"type,omitempty" yaml:"type,omitempty"`
	Default string `json:"default,omitempty" yaml:"default,omitempty"`
}

ReferenceFlag describes a single flag for Reference.

type ReferenceSub

type ReferenceSub struct {
	Name string `json:"name,omitempty" yaml:"name,omitempty"`
	Reference
}

type Store

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

func NewStore

func NewStore(extensionsDir string) *Store

func (*Store) FindAll

func (m *Store) FindAll() ([]Manifest, error)

FindAll scans path for extension manifest.yml files. It loads extension data from each manifest.yml and returns all loaded extension manifests.

func (*Store) Get

func (m *Store) Get(binaryName string) (Manifest, error)

func (*Store) Remove

func (m *Store) Remove(binaryName string) error

Remove removes the given extension. The full contents of the extension directory are removed. If the extension manifest points to a binary outside the directory, the binary is not removed. Returns ErrExtensionNotInstalled if the extension is not installed.

func (*Store) Write

func (m *Store) Write(ext Extension, binary io.Reader) (_ Manifest, err error)

type Unmanaged

type Unmanaged struct {
	Name       string
	BinaryName string
	Path       string
}

Unmanaged represents an extension not managed by the CLI.

func FindAllOnPATH

func FindAllOnPATH() []Unmanaged

FindAllOnPATH scans PATH for executables named "circleci-<name>" and returns the extension names (the part after "circleci-"). The first entry in PATH wins for duplicate names, matching exec.LookPath semantics.

func (*Unmanaged) Run

func (ext *Unmanaged) Run(ctx context.Context, client *apiclient.Client, args []string) error

Run executes the extension binary with args, injecting CircleCI environment variables.

The current process is replaced by the extension via syscall exec on Unix; on Windows the extension is run as a child process and its exit code is propagated.

If the extension binary is not found, ErrExtensionBinaryNotFound is returned and the caller should prompt the user to reinstall the extension.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL