cli

type AppConfig struct {
	SDProjects      []string
	BoardID         string
	BoardFilter     string
	ChecklistField  string
	FormsCountField string
}

type Cmd struct {
	MinArgs int // minimum positionals the handler requires
	Flags   CmdFlags
	Desc    string // one-line description for Usage listing
	Help    string // help text; first line is used in usage errors

	// Subcommands routes a command group; when set, Run is ignored.
	Subcommands *Dispatcher

	Run func(ctx context.Context, env *Env, args []string) error
}

type CmdFlags uint8

type ConfigDefaults struct {
	Board           string   `json:"board,omitzero"`
	BoardFilter     string   `json:"board_filter,omitzero"`
	SDProjects      []string `json:"sd_projects,omitzero"`
	ChecklistField  string   `json:"checklist_field,omitzero"`
	FormsCountField string   `json:"forms_count_field,omitzero"`
}

type ConfigFile struct {
	Site    string `json:"site"`
	CloudID string `json:"cloud_id,omitzero"`
	Email   string `json:"email"`
	// Token stores an inline API token. init defaults to a separate token file.
	Token     string `json:"token,omitzero"`
	TokenFile string `json:"token_file,omitzero"`
	// Scoped selects gateway URLs and Bearer auth for a scoped API token.
	Scoped   bool           `json:"scoped,omitzero"`
	Defaults ConfigDefaults `json:"defaults,omitzero"`
}

type Dispatcher struct {
	Name      string         // for errors and usage ("jcli" or "jcli wiki")
	Prefix    string         // Env.Command prefix ("" or "wiki ")
	Index     map[string]Cmd // subcommand name → spec
	Shortcuts []ShortcutDoc  // rendered in usage before Index

	Fallback Fallback
	Usage    func(w io.Writer)
}

type EmitOpts struct {
	Data       any            // payload; nil for pure mutations
	Action     string         // "commented", "created", "skipped", ...
	Key        string         // target resource identifier
	Meta       map[string]any // non-essential context
	Pagination *Pagination    // cursor-paginated results
	Human      func()         // human-mode closure (writes to env.Stdout)
}

type Env struct {
	Client   *jira.Client // nil until Connect runs; NoClient handlers never get one
	Cfg      AppConfig
	Paths    Paths
	Stdout   io.Writer
	Stderr   io.Writer
	JSONMode bool
	// Connect loads Client and Cfg when the dispatcher first needs them.
	Connect func(ctx context.Context) error
	// Command is the dispatched path (e.g. "wiki page"), included in JSON envelopes.
	Command string
	// contains filtered or unexported fields
}

type Envelope struct {
	Version    string         `json:"version"`
	Command    string         `json:"command"`
	Data       jsontext.Value `json:"data,omitzero"`
	Action     string         `json:"action,omitzero"`
	Key        string         `json:"key,omitzero"`
	Pagination *Pagination    `json:"pagination,omitzero"`
	Meta       map[string]any `json:"meta,omitzero"`
	Warnings   []string       `json:"warnings,omitzero"`
	Error      *ErrorDetail   `json:"error,omitzero"`
}

type ErrKind string

type ErrorDetail struct {
	Kind      ErrKind `json:"kind"`
	Retryable bool    `json:"retryable"`
	Hint      string  `json:"hint,omitzero"`
	Message   string  `json:"message"`
}

type Fallback func(args []string) (rewritten []string, handled bool, err error)

type FieldRecord struct {
	AllowedValues []string `json:"allowed_values,omitzero"`
	FieldID       string   `json:"field_id"`
	Name          string   `json:"name,omitzero"`
	Required      bool     `json:"required,omitzero"`
	SetExample    string   `json:"set_example,omitzero"`
	Supplied      any      `json:"supplied,omitzero"`
	Type          string   `json:"type,omitzero"`
}

type InputSource int

type MultiFlag []string

type Pagination struct {
	NextCursor string `json:"next_cursor,omitzero"`
	HasMore    bool   `json:"has_more"`
}

type Paths struct {
	Home      string
	ConfigDir string
}

type RawJSONer interface {
	RawJSON() jsontext.Value
}

type ShortcutDoc struct {
	Label string // e.g. "<ISSUE-KEY>" or "<PAGE-ID-OR-URL>"
	Desc  string
}

type ValidationError struct {
	Err           error         // joined per-issue errors (errors.Join)
	Hint          string        // short cue for ErrorDetail.Hint
	MissingFields []FieldRecord // required but absent → meta.missing_fields
	UnknownFields []FieldRecord // not in editmeta/createmeta → meta.unknown_fields
	InvalidValues []FieldRecord // value not in allowedValues → meta.invalid_values
}