presenter

Documentation

Index

• Constants
• Variables
• func ApplicationError(err error) error
• func CoalesceFocus(focus any) any
• func CoalesceState(state any) any
• func InvalidInput(message string, state any) error
• func MarshalEnvelope(envelope Envelope) ([]byte, error)
• func NormalizeNextActions(next []any) []any
• func SplitStateFocus(state any) (any, any)
• func WriteJSON(w io.Writer, envelope Envelope) error
• type Directive
  • func ChooseOne(options []any) Directive
  • func ChooseThenSequence(options []any) Directive
  • func CoalesceDirective(next Directive) Directive
  • func DirectiveForReadMode(mode string, next []any) Directive
  • func None() Directive
  • func Sequence(steps []any) Directive
• type Envelope
  • func ClassifyError(err error, ctx UnexpectedContext) Envelope
  • func ErrorEnvelope(err error) Envelope
  • func ReadEnvelope(state, focus any, next Directive) Envelope
  • func UnexpectedErrorEnvelope(err error, ctx UnexpectedContext) Envelope
  • func WriteEnvelope(state, focus, result any, next Directive) Envelope
• type Error
• type Failure
  • func (f *Failure) Error() string
• type UnexpectedContext

Constants

const IssueRepoURL = "https://github.com/aitoroses/specctl/issues/new"

IssueRepoURL is the destination for unexpected-error reports.

Variables

var BuildVersion = "dev"

BuildVersion is overridable at link time (-ldflags "-X ...BuildVersion=v1.2.3").

Functions

func ApplicationError

func ApplicationError(err error) error

func CoalesceFocus

func CoalesceFocus(focus any) any

func CoalesceState

func CoalesceState(state any) any

func InvalidInput

func InvalidInput(message string, state any) error

func MarshalEnvelope

func MarshalEnvelope(envelope Envelope) ([]byte, error)

MarshalEnvelope encodes an envelope to JSON, returning a fixed fallback payload (and a non-nil error) when encoding fails. Callers should always be able to write the returned bytes to the wire, even on failure.

func NormalizeNextActions

func NormalizeNextActions(next []any) []any

func SplitStateFocus

func SplitStateFocus(state any) (any, any)

func WriteJSON

func WriteJSON(w io.Writer, envelope Envelope) error

Types

type Directive

type Directive struct {
	Mode    string `json:"mode"`
	Steps   []any  `json:"steps,omitempty"`
	Options []any  `json:"options,omitempty"`
}

func ChooseOne

func ChooseOne(options []any) Directive

func ChooseThenSequence

func ChooseThenSequence(options []any) Directive

func CoalesceDirective

func CoalesceDirective(next Directive) Directive

func DirectiveForReadMode

func DirectiveForReadMode(mode string, next []any) Directive

func None

func None() Directive

func Sequence

func Sequence(steps []any) Directive

type Envelope

type Envelope struct {
	State  any       `json:"state"`
	Focus  any       `json:"focus"`
	Result any       `json:"result,omitempty"`
	Next   Directive `json:"next"`
	Error  *Error    `json:"error,omitempty"`
}

func ClassifyError

func ClassifyError(err error, ctx UnexpectedContext) Envelope

ClassifyError returns an envelope for any error coming out of the application layer. *Failure values keep their tipified codes; anything else is treated as unexpected and gets the report_issue hint.

func ErrorEnvelope

func ErrorEnvelope(err error) Envelope

func ReadEnvelope

func ReadEnvelope(state, focus any, next Directive) Envelope

func UnexpectedErrorEnvelope

func UnexpectedErrorEnvelope(err error, ctx UnexpectedContext) Envelope

UnexpectedErrorEnvelope produces an envelope for errors that look like bugs in specctl rather than user input problems. It embeds a report_issue step so MCP clients (or CLI consumers) can prompt the user to file a bug with the captured tool/input/error context.

func WriteEnvelope

func WriteEnvelope(state, focus, result any, next Directive) Envelope

type Error

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

type Failure

type Failure struct {
	Code    string
	Message string
	State   any
	Focus   any
	Next    Directive
}

func (*Failure) Error

func (f *Failure) Error() string

type UnexpectedContext

type UnexpectedContext struct {
	Tool       string
	Input      any
	PanicValue any
	Stack      string
}

UnexpectedContext carries the call-site information bundled into a report_issue hint so the agent can paste a complete bug report.