Documentation
¶
Overview ¶
Package sdk provides a high-level API for plugins to send output through the core CLI's centralized rendering engine.
Plugins do not construct protobuf messages themselves; they call the semantic methods here. Every method returns an error so callers can decide whether to fall back to local rendering — see Unsupported, which identifies the only two conditions under which falling back is safe.
Index ¶
- Variables
- func Unsupported(err error) bool
- type CLI
- func (c *CLI) Available() bool
- func (c *CLI) Error(msg string) error
- func (c *CLI) Message(msg string) error
- func (c *CLI) Output(command string, blocks ...OutputBlock) error
- func (c *CLI) Progress(msg string) error
- func (c *CLI) ProgressStart(msg string) (*Spinner, error)
- func (c *CLI) Prompt(opts PromptOpts) (string, error)
- func (c *CLI) Success(msg string) error
- func (c *CLI) Warn(msg string) error
- type OutputBlock
- type PromptOpts
- type PromptType
- type Spinner
Constants ¶
This section is empty.
Variables ¶
var ErrNoHelper = errorcategory.New(errorcategory.Internal, "no core CLI helper available")
ErrNoHelper is returned when the plugin was invoked without a core CLI helper (v1/v2 protocol, or standalone/dev mode). Callers should render locally.
Functions ¶
func Unsupported ¶
Unsupported reports whether err means the core CLI cannot render this output, which is the only case where a plugin may safely render it locally instead:
- ErrNoHelper: no helper was provided, so nothing was sent.
- gRPC Unimplemented: the core CLI predates this RPC, so nothing was rendered.
Any other error must be surfaced, not swallowed. A transport failure can happen after the core already rendered the output, and rendering locally in that case would show the user a duplicate.
Types ¶
type CLI ¶
type CLI struct {
// contains filtered or unexported fields
}
CLI wraps a CoreCLIHelper to provide convenient output methods for plugins.
func New ¶
func New(helper plugins.CoreCLIHelper) *CLI
New creates a new CLI SDK instance from a CoreCLIHelper. A nil helper is valid and yields a CLI whose Available reports false and whose methods return ErrNoHelper, so callers can use one code path for both cases.
func (*CLI) Output ¶
func (c *CLI) Output(command string, blocks ...OutputBlock) error
Output sends structured command output to core CLI. Only used for success output. For errors, use cli.Error() + return an error from the command (non-zero exit code).
Blocks are rendered in the order provided.
Usage:
cli.Output("apps upload",
sdk.Data(map[string]any{"app_id": "app_1234", "version": "1.0.0"}),
sdk.Warning("Your App ID is permanent once uploaded"),
sdk.NextStep("View status", "https://dashboard.stripe.com/apps/app_1234"),
)
func (*CLI) ProgressStart ¶
ProgressStart begins a spinner and returns a handle to control it.
The returned handle is always non-nil, so callers can defer Stop without a nil check even when the core CLI is unavailable.
func (*CLI) Prompt ¶
func (c *CLI) Prompt(opts PromptOpts) (string, error)
Prompt asks the user a question and returns their response.
type OutputBlock ¶
type OutputBlock struct {
// contains filtered or unexported fields
}
OutputBlock is a typed block of output data.
func Data ¶
func Data(v interface{}) OutputBlock
Data creates a data block with arbitrary key-value payload.
func NextStep ¶
func NextStep(description, command string) OutputBlock
NextStep creates a next-step block.
func NextStepWithCode ¶
func NextStepWithCode(code, description, command string) OutputBlock
NextStepWithCode creates a next-step block with an explicit code.
func WarningWithCode ¶
func WarningWithCode(code, msg string) OutputBlock
WarningWithCode creates a warning block with an explicit code.
type PromptOpts ¶
type PromptOpts struct {
Message string
Type PromptType
Default string
Options []string // required for PromptSelect
}
PromptOpts configures a prompt.
type PromptType ¶
type PromptType int
PromptType selects the kind of prompt to show.
const ( PromptText PromptType = 0 PromptConfirm PromptType = 1 PromptSelect PromptType = 2 )
Prompt kinds.
type Spinner ¶
type Spinner struct {
// contains filtered or unexported fields
}
Spinner represents an active progress spinner that can be updated and stopped.
Source Files