Documentation
¶
Overview ¶
Package recovery carries semantic recovery targets from error producers to the build-local error presenter. Producers describe which command a hint part points to; they do not inspect distribution or policy state.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Annotate ¶
Annotate associates err with a structured recovery hint. The error and its existing wire hint are not mutated. Error producers should keep the current textual hint on the typed error (normally hint.String()) so behavior remains unchanged when no presentation filtering is applied.
func AnnotateMessage ¶
AnnotateMessage associates err with a structured Problem.Message. The producer should initialize the typed error with message.String() so default callers and direct error formatting remain byte-for-byte unchanged.
func Attach ¶
Attach writes hint's fully-visible text to the owned typed error and annotates that exact producer for build-local projection. Callers should use it while constructing an error, before any later contextual enrichment.
func CloneTyped ¶
CloneTyped extracts and clones the first concrete errs typed error in err's chain. Shared Problem fields, every type-specific extension, and the typed error's Cause are preserved. Slice extensions are copied so subsequent presentation enrichment cannot mutate the producer's value through aliasing.
func Render ¶
Render returns a concrete typed-error clone suitable for presentation by one command tree. If err carries a recovery annotation, only the clone's Hint is filtered against plan. The source error is never mutated.
Untyped errors and raw-passthrough errors are returned unchanged. Raw errors intentionally bypass local presentation rewriting.
Types ¶
type Hint ¶
type Hint struct {
// contains filtered or unexported fields
}
Hint is an immutable sequence of semantic recovery parts. separator is used only between retained non-empty parts, so filtering one action cannot leave dangling punctuation such as a leading "; ".
func Join ¶
Join returns a hint that joins retained parts with separator. It defensively copies parts so callers cannot mutate the annotation later.
func JoinHints ¶
JoinHints composes independently renderable hints. Each child applies its own target filtering and fallback before the retained children are joined, allowing command-only recovery to keep a useful fallback alongside other policy guidance.
func UserAuthorization ¶
UserAuthorization returns canonical structured user-login recovery for producers that opt into this helper. Producers provide only the scopes they require; the command target, standard wording, and reduced-distribution fallback stay centralized.
func (Hint) WithFallback ¶
WithFallback returns a copy that renders text when projection removes every ordinary part. It is intended for command-only recovery: reduced distributions must not retain a dead command pointer, but callers still need a useful next step.
type Part ¶
type Part struct {
// contains filtered or unexported fields
}
Part is one immutable fragment of a recovery hint. A plain-text part has no target and is always retained; a command part is retained only while its target remains referenceable in the current command surface.
type Projector ¶
type Projector struct {
// contains filtered or unexported fields
}
Projector is a narrow, build-local presentation boundary for cmd-layer result renderers. Business producers describe semantic Targets and never receive the underlying Surface Plan.
The plan callback is evaluated lazily because commands are registered before plugin policy and distribution presentation have produced the final plan. A nil Projector, nil callback, or nil Plan means the default fully-visible surface.
func NewProjector ¶
NewProjector returns a projector backed by one command tree's plan callback.
func NewProjectorWithContext ¶
func NewProjectorWithContext(plan func() *surface.Plan, context RenderContext) *Projector
NewProjectorWithContext returns a projector whose presentation is scoped to both one command tree and one immutable invocation context.
func (*Projector) CanReference ¶
CanReference reports whether a semantic recovery target is available in this projector's command tree.
func (*Projector) RenderHint ¶
RenderHint projects one semantic hint for this command tree.
type RenderContext ¶
type RenderContext struct {
// Profile is the explicit --profile override from this invocation. An empty
// value means recovery commands retain their historical profile-free form.
Profile string
}
RenderContext carries invocation-local facts that affect recovery command rendering. It belongs to one command-tree build; business error producers do not receive it and therefore remain independent of CLI invocation details.
func (RenderContext) AuthLoginCommand ¶
func (c RenderContext) AuthLoginCommand(suffix string) string
AuthLoginCommand returns the auth-login command for this invocation. suffix is a code-owned argument fragment (for example "--device-code <code>"); the invocation profile is always emitted as one shell-safe argv value.
func (RenderContext) InlineAuthLoginCommand ¶
func (c RenderContext) InlineAuthLoginCommand(suffix string) string
InlineAuthLoginCommand wraps AuthLoginCommand in a Markdown code span. The default command keeps the historical single-backtick bytes; unusual profile values containing backticks receive a longer delimiter without changing the shell command itself.
type Target ¶
type Target string
Target is the canonical command path required by one recovery instruction. It is intentionally distinct from surface.CommandID so business packages can describe recovery semantics without depending on presentation policy.
const ( TargetAuthLogin Target = Target(surface.CommandAuthLogin) TargetConfig Target = Target(surface.CommandConfig) TargetConfigInit Target = Target(surface.CommandConfigInit) TargetConfigBind Target = Target(surface.CommandConfigBind) TargetConfigStrictMode Target = Target(surface.CommandConfigStrictMode) TargetConfigPolicyShow Target = Target(surface.CommandConfigPolicyShow) TargetConfigPluginsShow Target = Target(surface.CommandConfigPluginsShow) TargetProfile Target = Target(surface.CommandProfile) TargetProfileAdd Target = Target(surface.CommandProfileAdd) TargetProfileList Target = Target(surface.CommandProfileList) TargetSchema Target = Target(surface.CommandSchema) TargetUpdate Target = Target(surface.CommandUpdate) TargetSkills Target = Target(surface.CommandSkills) TargetSkillsRead Target = Target(surface.CommandSkillsRead) )
Framework recovery targets mirror surface's centralized canonical command IDs while keeping business packages dependent only on recovery semantics.
Source Files