cli

package
v0.10.6 Latest Latest
Warning

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

 Go to latest Published: Jul 8, 2026 License: MIT Imports: 43 Imported by: 0

Documentation

Overview

Plain-text renderer for `jira alias list`: one aligned `name → expansion` line per alias, natural-ordered by name, so the human output shows the same map the JSON envelope carries.

Plain-text renderer for `jira boards list`. See in the boards research notes for the column / truncation contract this file implements.

Index

Constants

View Source 
const (
	ErrorTypeAuth       = errtax.TypeAuth
	ErrorTypeNotFound   = errtax.TypeNotFound
	ErrorTypeValidation = errtax.TypeValidation
	ErrorTypeRateLimit  = errtax.TypeRateLimit
	ErrorTypeServer     = errtax.TypeServer
)

The taxonomy types, re-exported under cli's historical names.

Variables

View Source 
var ClassifyUntypedProbe func(error)

ClassifyUntypedProbe is a test seam: when non-nil, classifyUntyped reports every error that reaches the legacy substring classifier, so a test can prove an intentional command error is typed rather than substring-guessed. Nil in production; exported because the probing tests drive real commands from outside this package. Tests that set it must not run in parallel.

View Source 
var OutputModeValues = []string{"auto", "human", "json", "compact"}

OutputModeValues lists the accepted --output values for help text and shell completion.

Functions

func AggregateCode added in v0.10.6 

func AggregateCode(top Error) errtax.Code

AggregateCode is the errtax code a multi-key partial-failure should carry, derived from the worst already-classified per-key failure rather than re-guessed from the summary string. Falls back to the type's default code, then to validation, so the aggregate is never uncoded.

func ExitCode 

func ExitCode(err Error) int

ExitCode maps a structured Error to its process exit code: a registered code's pinned exit (canceled=6 and timeout=7 live in the registry as per-code rows), else the type's default.

func ForeignFlagSuggestions added in v0.10.0 

func ForeignFlagSuggestions(flag string) []string

ForeignFlagSuggestions resolves a flag name against the foreign-CLI table, tolerating leading dashes and case drift in how the parser reported it. It returns a fresh slice, or nil for a flag with no known equivalent. 

func Hyperlink(url, text string) string

Hyperlink builds an OSC 8 terminal hyperlink for url displayed as text. Both the URL and the display text are sanitized first so a control byte in Jira-supplied text cannot break the span open/close pair or smuggle a second hyperlink.

func HyperlinkPreStyled added in v0.10.0 

func HyperlinkPreStyled(url, styledText string) string

HyperlinkPreStyled links display text that already carries ANSI styling (which sanitization would strip). Callers sanitize the raw content BEFORE styling; the URL must already be sanitized too. Honors the user-level hyperlink switch on the default logger and emits through clog's primitive — no logger construction per link.

func KnownTotal added in v0.10.0 

func KnownTotal(total int) *int

KnownTotal wraps an authoritative total for Pagination.Total. Only call it with a value the endpoint actually reported.

func NewRequestID 

func NewRequestID() string

NewRequestID returns a 32-character hex request id. crypto/rand is the source; on the practically-impossible read failure it falls back to a timestamp seed, still hex-encoded and zero-padded so the id keeps its fixed 32-char shape for any consumer that parses it.

func RouteWarnings 

func RouteWarnings(opts RouteOptions) error

RouteWarnings is the single entry point that splits data vs warnings across stdout/stderr. Commands with structured warnings call this instead of WriteEnvelope/WriteCommandPlain directly.

func SanitizeCompletionField 

func SanitizeCompletionField(s string) string

SanitizeCompletionField makes a single shell-completion candidate field safe. Shell completion is one tab-separated record per line, so an embedded tab, newline or carriage return in a candidate field would corrupt the grammar; those are collapsed to single spaces. Control bytes are stripped as in SanitizeTerminalText.

func SanitizeTerminalBlock added in v0.10.0 

func SanitizeTerminalBlock(s string) string

SanitizeTerminalBlock makes multi-line display text safe for a terminal: ANSI escape sequences are stripped and control bytes dropped exactly as in SanitizeTerminalText, but tab and newline survive so legitimate multi-line Jira content (descriptions, comment bodies) keeps its layout. A CRLF is normalized to a newline and any bare carriage return is dropped, so Jira text cannot use a lone CR to overwrite earlier output on the line.

func SanitizeTerminalText 

func SanitizeTerminalText(s string) string

SanitizeTerminalText makes a string safe to write to a terminal at an output boundary. It first strips any ANSI escape sequences, then drops the remaining C0/C1 control bytes (including bare ESC, BEL and NUL) that Jira-controlled text could carry to corrupt the terminal or an OSC 8 hyperlink span. Printable text — including non-ASCII runes — is preserved unchanged.

func SentenceCase added in v0.4.0 

func SentenceCase(s string) string

SentenceCase upper-cases the first rune of s, leaving the rest untouched, so a lower-case verb phrase reads as user-facing UI text ("listed issues" -> "Listed issues") while an acronym already at the front survives ("JQL reference" stays). The verb registry stores lower-case forms for structured logs; the spinner, progress bar, and completion line apply this at render so the surfaces the user reads are Sentence-cased, matching git / cargo / docker and clog's own spinner examples.

func Suggest 

func Suggest(input string, candidates []string) []string

Suggest returns up to suggestionLimit candidates within suggestionMaxDistance edit distance of input, closest first. Candidates shorter than suggestionMinNameLen are skipped. The returned names are the raw candidate strings — the caller adds any "--" prefix.

This deliberately stays off xstrings.Closest: Suggestions is a multi-valued field fed by Cobra's own SuggestionsFor on the unknown-command path, and this helper keeps unknown-flag suggestions on the same contract — plain Levenshtein at Cobra's fixed distance-2 default, up to two candidates. Closest returns a single best match under a length-proportional Damerau threshold, which would change the error payload shape and break that parity.

func ValidateIssueColumns added in v0.3.0 

func ValidateIssueColumns(selected []string) error

ValidateIssueColumns reports whether every requested column name is known, so a command can fail fast before calling Jira.

func WriteAliasListPlain added in v0.10.0 

func WriteAliasListPlain(w io.Writer, command string, data any, opts ...PlainOption) error

WriteAliasListPlain renders the `alias.list` envelope data — the config's alias name→expansion map — for human consumption. An empty map says so explicitly, so "no aliases" is distinguishable from broken output.

func WriteAttachmentListPlain 

func WriteAttachmentListPlain(w io.Writer, command string, data any, opts ...PlainOption) error

WriteAttachmentListPlain renders the `issue.attachment.list` envelope for human consumption. Layout: a header line with the attachment count, followed by one row per attachment with id, filename, human bytes, uploader displayName, and a relative-time created marker.

Mirrors the plain_watcher / plain_link signature so the dispatcher in plain.go can wire it with the same `(w, command, data, opts)` shape.

func WriteBoardListPlain 

func WriteBoardListPlain(w io.Writer, command string, data any, opts ...PlainOption) error

WriteBoardListPlain renders the `boards.list` envelope's data block for human consumption. Layout: a header line with the board count, followed by a four-column table — id (right-aligned), name, type, projects (comma-joined with `+N` overflow at 3+ keys ). Empty list surfaces a single advisory line directing the user at the cache primer (the affordance).

Mirrors the plain_link / plain_watcher signature so the dispatcher in plain.go can wire it with the same `(w, command, data, opts)` shape.

func WriteCommandPlain 

func WriteCommandPlain(w io.Writer, command string, data any, opts ...PlainOption) error

WriteCommandPlain routes a command's data to the plain renderer that owns its human output. Per-command renderers in the plain_*.go files own the field order, human-size and time formatting for one command group; writeGenericPlain remains the fallback for low-risk internal data that has no dedicated renderer. The command set is closed, so an explicit switch is the whole dispatch — there is deliberately no parallel renderer registry.

func WriteCommentListPlain 

func WriteCommentListPlain(w io.Writer, command string, data any, opts ...PlainOption) error

WriteCommentListPlain renders the `data` payload from `comment list` as a TTY-friendly clog table. Designed to be wired into WriteCommandPlain's dispatcher (lead's integration commit handles the wiring).

Expected data shape (from cmd/jira/issue_comment.go's runCommentList): 

{
  "comments": [
    {
      "id": "100",
      "body": "...markdown...",
      "author": {"account_id": "...", "display_name": "Alice"},
      "update_author": {...} | null,
      "created": "2026-04-01T10:00:00.000+0000",
      "updated": "2026-04-01T10:00:00.000+0000",
      "visibility": {"type": "role", "value": "Developers"} | null
    }, ...
  ]
}

The renderer prints one line per comment with:

  • id (bold)
  • author display_name
  • created (raw, no relative-time math — Atlassian's RFC 3339 is enough)
  • "(edited)" marker when updated > created
  • visibility tag when set
  • body preview (first ~80 runes, newlines flattened)

Lossy-conversion warnings travel through the envelope's warnings[] array; the renderer doesn't repeat them inline (they're routed to stderr).

func WriteCompact 

func WriteCompact(w io.Writer, data any) error

WriteCompact serializes the JSON data payload to w without the envelope wrapper, with null-valued keys dropped recursively so the agent-facing payload stays lean. json and human modes keep the full, stable schema; compact is the deliberately lossy, token-economical view, so in compact an absent key means the value was null. A clog encode or write failure is surfaced to the caller rather than silently dropped.

func WriteEnvelope 

func WriteEnvelope(w io.Writer, env Envelope) error

WriteEnvelope serializes a full JSON envelope to w. A clog encode or write failure is surfaced to the caller rather than silently dropped.

func WriteEnvelopeDocument added in v0.10.6 

func WriteEnvelopeDocument(w io.Writer, doc any) error

WriteEnvelopeDocument serializes a pre-built envelope document (a value that already carries the ok/meta/data/errors/warnings shape — typically a map) through the same clog flat path cli.WriteEnvelope uses, so a broken-pipe or quota write failure surfaces via errWriter instead of being swallowed. It exists for the raw-warning path, whose warnings carry arbitrary structured fields the typed Warning struct does not model, so the document cannot be funneled through the typed Envelope without dropping data.

func WriteHumanJSON added in v0.1.1 

func WriteHumanJSON(w io.Writer, data any, printTheme *clogtheme.Theme) error

WriteHumanJSON serializes JSON through clog's pretty printer for endpoints whose human mode still has a structured JSON contract. printTheme, when non-nil, retints the syntax highlighting to match the user's resolved theme and terminal background, so highlighted JSON stays readable on a light terminal just as entity colors do; nil keeps clog's built-in dark palette.

func WriteIssueTransitionsPlain 

func WriteIssueTransitionsPlain(w io.Writer, command string, data any, opts ...PlainOption) error

func WriteIssueViewFailureDiagnostics added in v0.2.0 

func WriteIssueViewFailureDiagnostics(w io.Writer, data any, errorsOut []Error) error

WriteIssueViewFailureDiagnostics mirrors multi-key issue-view failures to stderr for human mode. stdout stays reserved for successful rows.

func WriteIssueViewPlain 

func WriteIssueViewPlain(w io.Writer, command string, data any, opts ...PlainOption) error

func WriteKeyedResultsFailureDiagnostics added in v0.2.0 

func WriteKeyedResultsFailureDiagnostics(w io.Writer, data any, errorsOut []Error) error

WriteKeyedResultsFailureDiagnostics writes the bounded failed-key summary for shared multi-key commands.

func WriteKeyedResultsPlain added in v0.2.0 

func WriteKeyedResultsPlain(w io.Writer, command string, data any, opts ...PlainOption) error

WriteKeyedResultsPlain renders the shared multi-key envelope. It keeps stdout focused on the successful per-key payloads; failed keys are mirrored to stderr by WriteKeyedResultsFailureDiagnostics.

func WriteLinkListPlain 

func WriteLinkListPlain(w io.Writer, command string, data any, opts ...PlainOption) error

func WriteLinkTypesPlain 

func WriteLinkTypesPlain(w io.Writer, command string, data any, opts ...PlainOption) error

func WritePlain 

func WritePlain(w io.Writer, data any) error

func WriteWatcherListPlain 

func WriteWatcherListPlain(w io.Writer, command string, data any, opts ...PlainOption) error

WriteWatcherListPlain renders the `issue.watchers.list` envelope for human consumption. Layout: a header line with the watcher count and a "(you are watching)" affordance when `is_watching: true`, followed by one row per watcher with displayName, truncated accountId, email (or `(hidden)` when the token can't surface it), and an active marker.

Mirrors the `plain_link.go` renderer's shape so the dispatcher in plain.go can wire it with the same `command/data/opts` signature.

Types

type AgentName 

type AgentName string

type CLIInputError 

type CLIInputError struct {
	Kind        CLIInputKind
	Message     string   // diagnosis: what failed
	Flag        string   // offending flag name (no dashes), when flag-scoped
	Suggestions []string // "did you mean" candidates, pre-formatted (e.g. "--output")
}

CLIInputError is the typed error every command-line input failure is wrapped in before it leaves the command layer — a bad flag, a missing required flag, the wrong positional-argument count, or an unknown command. It exists so MapError classifies the failure via errors.As instead of letting the substring classifier guess at an untyped Cobra string. Every CLIInputError is an exit-3 validation failure; the Kind supplies the specific code, and the errtax registry supplies the hint.

The struct carries only plain strings: the pflag/cobra inspection that produces it happens in the command layer, so internal/cli stays free of any Cobra dependency.

func NewCLIInputError 

func NewCLIInputError(kind CLIInputKind, message string) *CLIInputError

NewCLIInputError builds a CLIInputError of the given kind. Callers set Flag and Suggestions afterward when the failure is flag-scoped.

func (*CLIInputError) Code added in v0.10.0 

func (e *CLIInputError) Code() errtax.Code

Code is the stable snake_case envelope code for an input-failure kind.

func (*CLIInputError) Error 

func (e *CLIInputError) Error() string

func (*CLIInputError) FlagName added in v0.10.0 

func (e *CLIInputError) FlagName() string

FlagName names the offending flag when the failure is flag-scoped. The method is FlagName (not Flag) because Flag is a field.

type CLIInputKind 

type CLIInputKind int

CLIInputKind names which class of command-line input a CLIInputError reports. Each kind maps 1:1 to a stable snake_case envelope code, so an agent branches on Error.Code without parsing the message. 

const (
	// InputFlagUnknown is an unrecognized --flag.
	InputFlagUnknown CLIInputKind = iota
	// InputFlagValueMissing is a flag that requires a value but got none.
	InputFlagValueMissing
	// InputFlagValueInvalid is a flag value that failed type or range parsing.
	InputFlagValueInvalid
	// InputFlagSyntaxInvalid is a malformed flag token.
	InputFlagSyntaxInvalid
	// InputRequiredFlagMissing is a required flag that was not set.
	InputRequiredFlagMissing
	// InputArgCountInvalid is the wrong number of positional arguments.
	InputArgCountInvalid
	// InputCommandUnknown is an unrecognized subcommand.
	InputCommandUnknown
	// InputArgValueInvalid is a positional argument value outside the accepted set.
	InputArgValueInvalid
	// InputIssueTypeUnknown is a --type value naming no issue type on the
	// project's create screen — resolved against the fetched list in-code, so a
	// miss is validation, not a Jira 404.
	InputIssueTypeUnknown
	// InputSavedQueryUnknown is a `search saved NAME` value that matches no
	// saved query in the queries directory — a local-file lookup, so its hint
	// points at that directory rather than at --help.
	InputSavedQueryUnknown
	// InputForceRequired is a destructive or state-wiping run refused
	// because headless / agent / --no-input context needs explicit --force
	// consent.
	InputForceRequired
)

type CodedError added in v0.10.6 

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

CodedError attaches an explicit errtax.Code to a plain message. A site that already knows the correct classification — e.g. a multi-key runner that has each failure's typed code in hand — emits the code directly instead of leaving MapError to guess it from the message text. It wraps an optional cause so errors.Is/As still walk the chain.

func NewCodedError added in v0.10.6 

func NewCodedError(code errtax.Code, msg string) *CodedError

NewCodedError builds a typed error carrying code and message.

func WrapCoded added in v0.10.6 

func WrapCoded(code errtax.Code, msg string, cause error) *CodedError

WrapCoded is NewCodedError that also retains cause for errors.Is/As.

func (*CodedError) Code added in v0.10.6 

func (e *CodedError) Code() errtax.Code

func (*CodedError) Error added in v0.10.6 

func (e *CodedError) Error() string

func (*CodedError) Unwrap added in v0.10.6 

func (e *CodedError) Unwrap() error

type CommandSchema 

type CommandSchema struct {
	Command      string         `json:"command"`
	Flags        []FlagSchema   `json:"flags,omitempty"`
	OutputSchema map[string]any `json:"output_schema,omitempty"`
}

type Detection 

type Detection struct {
	Mode      Mode
	IsTTY     bool
	Agent     bool
	AgentName string
	// StdinPiped reports that stdin is NOT an interactive terminal (a pipe,
	// redirect, or /dev/null). It is deliberately negative so the zero value
	// means "interactive" — the safe default for code that builds a Detection
	// without a real stdin. Set from the runtime's stdin in PersistentPreRunE.
	StdinPiped bool
}

func Detect 

func Detect(stdout *os.File) Detection

func RequireTTY 

func RequireTTY(stdout *os.File) (Detection, error)

type Envelope 

type Envelope struct {
	OK       bool      `json:"ok"`
	Meta     Meta      `json:"meta"`
	Data     any       `json:"data"`
	Errors   []Error   `json:"errors"`
	Warnings []Warning `json:"warnings"`
}

Envelope is the machine-readable JSON output contract. ok is always emitted; a successful command sets ok:true and a failed command sets ok:false with data:null and a populated errors slice.

func ErrorEnvelope 

func ErrorEnvelope(command string, err error) Envelope

ErrorEnvelope builds a failure envelope: ok:false, data:null, meta.exit_code set, and a single structured error. Machine envelopes omit meta.profile entirely.

type Error 

type Error struct {
	Type      string `json:"type"`
	Code      string `json:"code"`
	Message   string `json:"message"`
	Hint      string `json:"hint"`
	Retryable bool   `json:"retryable"`

	// Flag / Field / Path scope a validation failure to an input;
	// Suggestions carries "did you mean" candidates for it, pre-formatted
	// as the caller would type them (e.g. "--output").
	Flag        string   `json:"flag,omitempty"`
	Field       string   `json:"field,omitempty"`
	Path        string   `json:"path,omitempty"`
	Suggestions []string `json:"suggestions,omitempty"`

	// HTTPStatus / RetryAfterSeconds carry transport metadata.
	HTTPStatus         int `json:"http_status,omitempty"`
	RetryAfterSeconds  int `json:"retry_after_seconds,omitempty"`
	RateLimitRemaining int `json:"rate_limit_remaining,omitempty"`

	// Provider / UpstreamCode / UpstreamStatus preserve a backend's own
	// failure identity. UpstreamCode stays empty when the provider
	// exposes no stable machine code (Jira does not).
	Provider       string `json:"provider,omitempty"`
	UpstreamCode   string `json:"upstream_code,omitempty"`
	UpstreamStatus int    `json:"upstream_status,omitempty"`
	// UpstreamRequestID is Jira's trace id for the failed exchange
	// (Atl-Traceid / X-ARequestId) — the value Atlassian support can
	// correlate, unlike the locally generated meta.request_id.
	UpstreamRequestID string `json:"upstream_request_id,omitempty"`

	// UpstreamMessages / UpstreamFieldErrors preserve Jira's
	// ErrorCollection body verbatim. Wording is not contractual; these
	// are diagnostic context, never a branch target.
	UpstreamMessages    []string          `json:"upstream_messages,omitempty"`
	UpstreamFieldErrors map[string]string `json:"upstream_field_errors,omitempty"`

	// Candidates carries structured disambiguation context — populated by
	// the watcher resolver when /user/search returns 2+ matches.
	Candidates []map[string]any `json:"candidates,omitempty"`
}

Error is one structured failure entry in the envelope errors slice. type, code, message, hint, and retryable are always present; agents branch on code (stable snake_case), never on message. The remaining fields are optional context, omitted when empty.

message and hint are disjoint. message states what failed — a diagnosis, not a wording contract; it may carry summarized upstream text. hint states what to do next — remediation; it may name commands, fields, or retry behavior. Remediation never belongs in message, and a diagnosis never belongs in hint.

func MapError 

func MapError(err error) Error

MapError is the central error mapper. Typed source errors describe themselves with an errtax.Code; the registry supplies everything derivable from it, and the capability interfaces layer per-instance context on top. Classification runs in tiers — never substring matching where a typed error exists: 

tier 1: prompt identity beats a wrapped cancellation — a canceled
        prompt is prompt_canceled, not canceled.
tier 2: bare or wrapped stdlib context sentinels. errors.Is walks the
        chain, so a Coded error wrapping a cancellation (an APIError
        whose Cause is a canceled body read, a CredentialError whose
        Wrapped is a keyring deadline) still classifies as
        canceled/timeout, preserving the pre-registry adapter order.
tier 3: every other Coded error; the outermost one in the chain wins.

A bare error falls back to a best-effort substring classifier for legacy untyped error strings; that tier is strictly terminal.

type ErrorType 

type ErrorType = errtax.Type

ErrorType aliases the shared taxonomy type; the historical cli names remain for the command layer.

type FlagSchema 

type FlagSchema struct {
	Name string `json:"name"`
	Type string `json:"type"`
}

type Meta 

type Meta struct {
	Command           string      `json:"command"`
	ExitCode          *int        `json:"exit_code,omitempty"`
	Timestamp         string      `json:"timestamp"`
	RequestID         string      `json:"request_id,omitempty"`
	UpstreamRequestID string      `json:"upstream_request_id,omitempty"`
	Pagination        *Pagination `json:"pagination,omitempty"`
}

Meta is the envelope's command-context block. Machine envelopes omit profile entirely — a command that must report a profile puts it in command-specific data. ExitCode is present only on failure envelopes.

RequestID is a locally generated correlation id; UpstreamRequestID is Jira's own trace id (Atl-Traceid / X-ARequestId) for the exchange — the value to quote to Atlassian support — present whenever the command had a Jira response to read it from.

type Mode 

type Mode string
const (
	ModePlain   Mode = "plain"
	ModeTUI     Mode = "tui"
	ModeJSON    Mode = "json"
	ModeCompact Mode = "compact"
)

func ResolveOutputMode 

func ResolveOutputMode(out OutputMode, det Detection) Mode

ResolveOutputMode turns the --output flag value plus auto-detection into the concrete rendering Mode. An explicit value overrides detection; OutputAuto follows the Detection.Mode produced by Detect.

type NotFoundError added in v0.10.6 

type NotFoundError struct {
	// Message is the user-facing diagnosis; when empty the wrapped
	// error's text is used verbatim.
	Message string
	Err     error
}

NotFoundError is the typed not_found (exit 2) wrapper for a resource the command proved absent — e.g. a live /user/search that returned zero matches. It wraps the cause so errors.Is still recognizes sentinels like jira.ErrUserNotFound, and carries the stable code so MapError never falls back to the substring classifier.

func NewNotFoundError added in v0.10.6 

func NewNotFoundError(message string, err error) *NotFoundError

NewNotFoundError wraps err as a typed not_found failure. An empty message keeps the wrapped error's text.

func (*NotFoundError) Code added in v0.10.6 

func (e *NotFoundError) Code() errtax.Code

Code is the stable not_found envelope code (exit 2).

func (*NotFoundError) Error added in v0.10.6 

func (e *NotFoundError) Error() string

func (*NotFoundError) Unwrap added in v0.10.6 

func (e *NotFoundError) Unwrap() error

type OperationVerb added in v0.4.0 

type OperationVerb struct {
	Gerund     string // "caching", "creating", "deleting"
	Past       string // "cached", "created", "deleted"
	Infinitive string // "cache", "create", "delete"
	Noun       string // "boards", "issue", "worklog"
}

OperationVerb carries an operation's verb in the three forms status output needs: a present-progressive gerund while the work runs ("caching"), a past-tense confirmation on success ("cached"), and an infinitive for failures ("failed to cache …"). Noun names the object acted on.

Forms are lower case to match the house log style — clog's own lines and the plain completion messages are lower case. The message is a terse event string; the variable detail (issue key, elapsed time, failure reason) travels as structured fields (key=, time=, reason=), never baked into these phrases.

func VerbFor added in v0.4.0 

func VerbFor(op string) OperationVerb

VerbFor returns the verb forms for an operation. An unknown operation falls back to a generic "processing" set so callers always get usable phrases.

func (OperationVerb) Failuref added in v0.4.0 

func (v OperationVerb) Failuref() string

Failuref returns the failure phrase, "failed to create issue".

func (OperationVerb) GerundPlural added in v0.4.0 

func (v OperationVerb) GerundPlural() string

GerundPlural returns the in-progress batch phrase, "listing issues".

func (OperationVerb) Gerundf added in v0.4.0 

func (v OperationVerb) Gerundf() string

Gerundf returns the in-progress phrase, "creating issue".

func (OperationVerb) NounPlural added in v0.4.0 

func (v OperationVerb) NounPlural() string

NounPlural returns the object noun in plural form for batch phrases — naive pluralisation (append s unless already plural) that covers the operations' nouns: issue -> issues, transition -> transitions, web link -> web links.

func (OperationVerb) PastPlural added in v0.4.0 

func (v OperationVerb) PastPlural() string

PastPlural returns the success batch phrase, "viewed issues" — the plural counterpart of Pastf for multi-key summaries.

func (OperationVerb) Pastf added in v0.4.0 

func (v OperationVerb) Pastf() string

Pastf returns the success phrase, "created issue".

type OutputMode 

type OutputMode string

OutputMode is the value of the canonical --output flag. It is the ONLY output-mode selector: the legacy --json/--compact/--plain/--raw booleans are removed and there is no raw REST passthrough mode. 

const (
	// OutputAuto defers to terminal/agent detection: TTY -> human,
	// non-TTY -> json, detected agent -> compact.
	OutputAuto OutputMode = "auto"
	// OutputHuman forces the rich clog/table renderer.
	OutputHuman OutputMode = "human"
	// OutputJSON forces the full JSON envelope (ok/meta/data/warnings/errors).
	OutputJSON OutputMode = "json"
	// OutputCompact forces the JSON data payload without the envelope
	// wrapper (no ok/meta/warnings/errors).
	OutputCompact OutputMode = "compact"
)

func ParseOutputMode 

func ParseOutputMode(v string) (OutputMode, error)

ParseOutputMode validates a raw --output flag value. An empty string resolves to OutputAuto. Any other unrecognized value — including the removed "raw"/"plain"/"tui" names — is rejected.

type Pagination 

type Pagination struct {
	StartAt    int    `json:"startAt"` //nolint:revive // pagination-exempt
	MaxResults int    `json:"maxResults"`
	Total      *int   `json:"total,omitempty"`
	IsLast     bool   `json:"isLast"`
	NextCursor string `json:"nextCursor,omitempty"`
}

Pagination is the JSON envelope's output-shape descriptor for paginated responses. The startAt/nextPageToken fields here describe the SHAPE the CLI emits — they are not cursor-management state in command code. pagination-exempt: output-shape only, not consumer-side cursor management.

This is the ONE pagination shape and it lives in ONE place: meta.pagination on single-target reads, and results[].data.pagination (same shape) inside keyed multi-key results. isLast and nextCursor are the authoritative walk signals; total appears only when the endpoint reports a real total — token-paged endpoints (enhanced search) never do, so a fabricated 0 is never emitted.

type PlainOption 

type PlainOption func(*plainConfig)

func WithPlainBaseURL 

func WithPlainBaseURL(baseURL string) PlainOption

func WithPlainColumns added in v0.3.0 

func WithPlainColumns(columns []string) PlainOption

WithPlainColumns selects and orders the issue-list columns for human and TSV output. An empty slice keeps the default column set.

func WithPlainDebug added in v0.2.0 

func WithPlainDebug(debug bool) PlainOption

func WithPlainGraphemeWidth added in v0.10.0 

func WithPlainGraphemeWidth(grapheme bool) PlainOption

WithPlainGraphemeWidth selects grapheme-cluster width measurement for table alignment, for terminals that draw grapheme clusters (mode 2027) as single glyphs. The default per-rune wcwidth measurement misaligns rows containing ZWJ or VS16 emoji sequences on such terminals.

func WithPlainParallel added in v0.2.0 

func WithPlainParallel(parallel bool) PlainOption

func WithPlainResultKey added in v0.10.0 

func WithPlainResultKey(key string) PlainOption

WithPlainResultKey names the multi-key entry the rendered data belongs to, making identification the child renderer's job instead of a duplicated heading above it.

func WithPlainTSV added in v0.3.0 

func WithPlainTSV(tsv bool) PlainOption

WithPlainTSV renders the issue list as tab-separated values instead of the styled table — one header line plus one line per issue, no ANSI or box.

func WithPlainTTY 

func WithPlainTTY(tty bool) PlainOption

func WithPlainTermWidth 

func WithPlainTermWidth(width int) PlainOption

func WithPlainTheme 

func WithPlainTheme(theme *clibtheme.Theme) PlainOption

func WithPlainThreads added in v0.2.0 

func WithPlainThreads(threads int) PlainOption

type PromptError 

type PromptError struct {
	Kind   PromptKind
	Prompt string // the prompt that failed, e.g. "auth login"
	Err    error  // the underlying cause (huh.ErrUserAborted, context.Canceled, …)
}

PromptError is the typed error every interactive-prompt failure is wrapped in before it leaves a command handler. It exists so MapError classifies prompt outcomes via errors.As instead of letting the substring classifier misread "auth login aborted" as an auth failure.

func NewPromptError 

func NewPromptError(kind PromptKind, prompt string, err error) *PromptError

NewPromptError builds a PromptError for the given prompt and cause.

func (*PromptError) Code added in v0.10.0 

func (e *PromptError) Code() errtax.Code

Code is the stable snake_case envelope code for a prompt kind.

func (*PromptError) Error 

func (e *PromptError) Error() string

func (*PromptError) Unwrap 

func (e *PromptError) Unwrap() error

type PromptKind 

type PromptKind int

PromptKind names why an interactive prompt did not yield a value. 

const (
	// PromptAborted means the user dismissed the prompt (Esc / Ctrl-C in
	// the form) before submitting.
	PromptAborted PromptKind = iota
	// PromptCanceled means the prompt was canceled by the command
	// context — a SIGINT or an elapsed --timeout.
	PromptCanceled
	// PromptUnavailable means a prompt was required but could not be
	// shown — no TTY, or --no-input was set.
	PromptUnavailable
)

type ReleaseNotesResult added in v0.10.0 

type ReleaseNotesResult struct {
	Releases []changelog.Release `json:"releases"`
	// Markdown is the notes to display in human output; excluded from JSON,
	// where Releases is the structured form.
	Markdown string `json:"-"`
}

ReleaseNotesResult is the envelope payload for `jira release-notes`: jira-cli's own embedded changelog. Releases carries the structured notes (newest first, or a single release when one is requested) and is what JSON consumers read — for a single release or --latest it holds one entry, so `.releases[0]` is that release. Markdown drives the human renderer and is excluded from JSON. It is shared with the releasenotes command package, which builds it, so the JSON envelope and the human renderer agree on one shape.

type RouteMode 

type RouteMode int

RouteMode selects how RouteWarnings emits data + warnings. 

const (
	// RouteJSON emits the full Envelope (data + warnings) on stdout. Stderr
	// stays untouched.
	RouteJSON RouteMode = iota
	// RoutePlain emits human-readable data on stdout and mirrors each
	// warning to stderr as a clog WRN line. Warning text MUST NOT
	// leak into stdout.
	RoutePlain
	// RouteCompact is JSON without the envelope wrapper; warnings still go
	// in the data via the caller's contract since there is no envelope.
	RouteCompact
)

type RouteOptions 

type RouteOptions struct {
	Stdout   io.Writer
	Stderr   io.Writer
	Mode     RouteMode
	Envelope Envelope      // used when Mode == RouteJSON
	Command  string        // used when Mode == RoutePlain
	Data     any           // used when Mode == RoutePlain
	Warnings []Warning     // used when Mode == RoutePlain (and may be empty)
	Plain    []PlainOption // optional plain renderer hints
}

RouteOptions describes a single envelope routing call.

type SchemaRegistry 

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

func NewSchemaRegistry 

func NewSchemaRegistry() *SchemaRegistry

func (*SchemaRegistry) Commands 

func (r *SchemaRegistry) Commands() []string

func (*SchemaRegistry) Get 

func (r *SchemaRegistry) Get(command string) (CommandSchema, bool)

func (*SchemaRegistry) Register 

func (r *SchemaRegistry) Register(schema CommandSchema)

type Warning 

type Warning struct {
	Type     string `json:"type"`
	Message  string `json:"message"`
	Field    string `json:"field,omitempty"`
	Path     string `json:"path,omitempty"`
	NodeType string `json:"node_type,omitempty"`
	MarkType string `json:"mark_type,omitempty"`
	Lossy    bool   `json:"lossy"`
}

Warning is a non-fatal best-effort diagnostic emitted alongside data. lossy is mandatory and serialized even when false; consumers branch on it without nil checks. field/path/node_type/mark_type are optional context fields.

func WarningFrom 

func WarningFrom(src WarningSource) Warning

WarningFrom adapts any WarningSource into a cli.Warning ready for the envelope. Used by command code converting pkg/adf warnings.

type WarningSource 

type WarningSource interface {
	WarningType() string
	WarningMessage() string
	WarningField() string
	WarningPath() string
	WarningNodeType() string
	WarningMarkType() string
	WarningIsLossy() bool
}

WarningSource is anything that can describe itself as a cli.Warning. The pkg/adf Warning satisfies this; we keep cli ignorant of pkg/adf to avoid the import cycle (pkg/adf -> cli -> pkg/adf via the plain renderer).

Source Files

View all Source files

Directories

Path Synopsis
Package adfcmd implements the `jira adf` command group: standalone Markdown→ADF conversion and linting, plus the explicitly-lossy ADF→Markdown projection.
 Package adfcmd implements the `jira adf` command group: standalone Markdown→ADF conversion and linting, plus the explicitly-lossy ADF→Markdown projection.
Package adfmode resolves the strict vs best-effort ADF mode for a given CLI invocation, applying both the precedence ladder and per-path defaults.
 Package adfmode resolves the strict vs best-effort ADF mode for a given CLI invocation, applying both the precedence ladder and per-path defaults.
`jira boards` command tree.
 `jira boards` command tree.
Package boardscope resolves the `--board NAME` / `--board-id N` flag pair against the local board cache and renders the result into JQL clauses and envelope data.
 Package boardscope resolves the `--board NAME` / `--board-id N` flag pair against the local board cache and renders the result into JQL clauses and envelope data.
registry
Package registry is the single source of truth for the cacheable Jira metadata resources: their identity, default freshness window, and fetch.
 Package registry is the single source of truth for the cacheable Jira metadata resources: their identity, default freshness window, and fetch.
Package cmdutil holds the cross-cutting helper layer shared by every jira-cli command: envelope writers, client/profile accessors, output-mode resolution, mutation gates, the credential-warning sink, and small generic value helpers.
 Package cmdutil holds the cross-cutting helper layer shared by every jira-cli command: envelope writers, client/profile accessors, output-mode resolution, mutation gates, the credential-warning sink, and small generic value helpers.
Package config implements the `jira config` cobra command tree, which manages the local configuration file, profiles, and theme settings.
 Package config implements the `jira config` cobra command tree, which manages the local configuration file, profiles, and theme settings.
`jira issue link` command tree.
 `jira issue link` command tree.
Package releasenotes implements `jira release-notes`, which prints jira-cli's own changelog — embedded in the binary — so a user can see what changed in the tool without opening GitHub or the docs site.
 Package releasenotes implements `jira release-notes`, which prints jira-cli's own changelog — embedded in the binary — so a user can see what changed in the tool without opening GitHub or the docs site.
Package runtime is the dependency boundary between the binary shell in cmd/jira and the command implementations.
 Package runtime is the dependency boundary between the binary shell in cmd/jira and the command implementations.
Package startup parses jira's global flags and first subcommand out of the raw argv before cobra runs.
 Package startup parses jira's global flags and first subcommand out of the raw argv before cobra runs.
Package stdin is the ONLY place in the source tree allowed to read os.Stdin.
 Package stdin is the ONLY place in the source tree allowed to read os.Stdin.
Package tui wires the `jira tui` command to the section-based dashboard.
 Package tui wires the `jira tui` command to the section-based dashboard.
Package update implements the `jira update` cobra command, which self-updates a release-archive binary in place and points Scoop and go-install binaries at the command their channel manages updates with.
 Package update implements the `jira update` cobra command, which self-updates a release-archive binary in place and points Scoop and go-install binaries at the command their channel manages updates with.
Package version implements the `jira version` cobra command: a bare version string for humans (and tooling that probes `<binary> version`), a labeled metadata block behind --detailed, and the structured envelope in machine modes.
 Package version implements the `jira version` cobra command: a bare version string for humans (and tooling that probes `<binary> version`), a labeled metadata block behind --detailed, and the structured envelope in machine modes.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.