output

package
v1.2.2 Latest Latest
Warning

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

 Go to latest Published: Jun 14, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Index

Constants

View Source 
const SchemaVersion = "1.0"
View Source 
const UntrustedKey = "_untrusted"

Variables

View Source 
var Compact bool

Compact controls whether JSON is emitted without indentation (set by --compact).

View Source 
var DurationMS func() int64

DurationMS returns the current command duration for response metadata. The cmd package sets this hook; package-level tests and helper use default to 0.

View Source 
var Quiet bool

Quiet suppresses all non-error output when true.

Functions

func Bold 

func Bold(msg string)

Bold prints a bold message to stdout.

func BranchToMap 

func BranchToMap(b FlatBranch) map[string]any

BranchToMap converts a FlatBranch to a map for field filtering.

func CommitToMap 

func CommitToMap(c FlatCommit) map[string]any

CommitToMap converts a FlatCommit to a map for field filtering.

func Error 

func Error(msg string)

Error prints a red cross message to stderr.

func FilterMap 

func FilterMap(m map[string]any, fieldNames []string) map[string]any

FilterMap returns a copy of m containing only the keys requested in fieldNames. Lookup is CASE-INSENSITIVE (so --fields webUrl, weburl, WEBURL all work) but the result preserves the canonical key from m (so output JSON always uses the same key the schema documents).

func FormatBlue 

func FormatBlue(s string) string

FormatBlue returns a blue formatted string.

func FormatCyan 

func FormatCyan(s string) string

FormatCyan returns a cyan formatted string.

func FormatCyanBold 

func FormatCyanBold(s string) string

FormatCyanBold returns a cyan bold formatted string.

func FormatGray 

func FormatGray(s string) string

FormatGray returns a gray formatted string.

func FormatGreen 

func FormatGreen(s string) string

FormatGreen returns a green formatted string.

func FormatRed 

func FormatRed(s string) string

FormatRed returns a red formatted string.

func FormatYellow 

func FormatYellow(s string) string

FormatYellow returns a yellow formatted string.

func Gray 

func Gray(msg string)

Gray prints a gray message to stdout.

func HintForErrorCode 

func HintForErrorCode(code ErrorCode) string

HintForErrorCode returns an actionable hint for the given error code.

func ID added in v1.2.1 

func ID(v any) string

ID renders numeric backend identifiers as strings for stable agent contracts.

func Info 

func Info(msg string)

Info prints a blue info message to stdout.

func IssueDetailToMap added in v1.2.2 

func IssueDetailToMap(f FlatIssue) map[string]any

IssueDetailToMap is the single-issue read shape: it adds the full description body (tagged _untrusted) that IssueToMap omits for token efficiency.

func IssueToMap 

func IssueToMap(f FlatIssue) map[string]any

IssueToMap converts a FlatIssue to a map for field filtering (list shape, no body).

func JobToMap 

func JobToMap(j FlatJob) map[string]any

JobToMap converts a FlatJob to a map for field filtering.

func LabelToMap 

func LabelToMap(f FlatLabel) map[string]any

LabelToMap converts a FlatLabel to a map for field filtering.

func MRDetailToMap added in v1.2.2 

func MRDetailToMap(m FlatMR) map[string]any

MRDetailToMap is the single-MR read shape: it adds the full description body (tagged _untrusted) that MRToMap omits for token efficiency.

func MRNoteToMap 

func MRNoteToMap(n FlatMRNote) map[string]any

MRNoteToMap converts a FlatMRNote to a map for field filtering.

func MRToMap 

func MRToMap(m FlatMR) map[string]any

MRToMap converts a FlatMR to a map for field filtering (list shape, no body).

func MarkUntrusted added in v1.2.1 

func MarkUntrusted(m map[string]any, fields ...string) map[string]any

MarkUntrusted annotates fields that originate from external GitLab content.

func MilestoneToMap 

func MilestoneToMap(f FlatMilestone) map[string]any

MilestoneToMap converts a FlatMilestone to a map for field filtering.

func PipelineToMap 

func PipelineToMap(p FlatPipeline) map[string]any

PipelineToMap converts a FlatPipeline to a map for field filtering.

func PrintErrorJSON 

func PrintErrorJSON(msg string, statusCode int)

PrintErrorJSON outputs the machine-readable error envelope as the single JSON document on stdout (CLI-SPEC §4): agents always parse stdout.

func PrintErrorJSONWithCode 

func PrintErrorJSONWithCode(msg string, statusCode int, code ErrorCode)

PrintErrorJSONWithCode outputs an error envelope with an explicit error code.

func PrintJSON 

func PrintJSON(v any)

PrintJSON outputs v as indented JSON to stdout. Marshal errors are written to stderr and terminate the process with exit code 2.

func PrintJSONErr 

func PrintJSONErr(v any) error

PrintJSONErr outputs v as JSON to stdout. On marshal failure it writes to stderr and returns the error (callers may map this to exit code 2).

func ProjectMemberToMap 

func ProjectMemberToMap(m FlatProjectMember) map[string]any

ProjectMemberToMap converts a FlatProjectMember to a map for field filtering.

func ProjectToMap 

func ProjectToMap(p FlatProject) map[string]any

ProjectToMap converts a FlatProject to a map for field filtering.

func ReleaseToMap 

func ReleaseToMap(r FlatRelease) map[string]any

ReleaseToMap converts a FlatRelease to a map for field filtering.

func RetryableErrorCode added in v1.2.0 

func RetryableErrorCode(code ErrorCode) bool

func SearchBlobToMap 

func SearchBlobToMap(b FlatSearchBlob) map[string]any

SearchBlobToMap converts FlatSearchBlob to a map for field filtering.

func SearchCommitToMap 

func SearchCommitToMap(c FlatSearchCommit) map[string]any

SearchCommitToMap converts FlatSearchCommit to a map for field filtering.

func SearchIssueToMap 

func SearchIssueToMap(i FlatSearchIssue) map[string]any

SearchIssueToMap converts FlatSearchIssue to a map for field filtering.

func SearchMRToMap 

func SearchMRToMap(m FlatSearchMR) map[string]any

SearchMRToMap converts FlatSearchMR to a map for field filtering.

func SearchProjectToMap 

func SearchProjectToMap(p FlatSearchProject) map[string]any

SearchProjectToMap converts FlatSearchProject to a map for field filtering.

func StatusBadge 

func StatusBadge(state string) string

StatusBadge returns a colored string based on a generic state name. GitLab states: opened/closed/merged/locked/running/pending/success/failed/canceled/skipped/manual/created/scheduled.

func Success 

func Success(msg string)

Success prints a green checkmark message to stdout.

func Table 

func Table(headers []string, rows [][]string)

Table prints a bordered, colored table.

func TreeEntryToMap 

func TreeEntryToMap(e FlatTreeEntry) map[string]any

TreeEntryToMap converts a FlatTreeEntry to a map for field filtering.

func UserToMap 

func UserToMap(u FlatUser) map[string]any

UserToMap converts a FlatUser to a map for field filtering.

func VariableToMap 

func VariableToMap(f FlatVariable) map[string]any

VariableToMap converts a FlatVariable to a map for field filtering.

func VariableWithValueToMap 

func VariableWithValueToMap(f FlatVariableWithValue) map[string]any

VariableWithValueToMap converts a FlatVariableWithValue to a map for field filtering.

func Warn 

func Warn(msg string)

Warn prints a yellow warning message to stderr.

Types

type Envelope added in v1.2.0 

type Envelope struct {
	OK            bool   `json:"ok"`
	SchemaVersion string `json:"schema_version"`
	Data          any    `json:"data,omitempty"`
	// Meta is always emitted (no omitempty): every response carries meta, and
	// duration_ms:0 is a valid value an agent should always see.
	Meta  Meta           `json:"meta"`
	Error *EnvelopeError `json:"error,omitempty"`
}

func ErrorEnvelope added in v1.2.0 

func ErrorEnvelope(msg string, statusCode int, code ErrorCode) Envelope

func SuccessEnvelope added in v1.2.0 

func SuccessEnvelope(v any) Envelope

type EnvelopeError added in v1.2.0 

type EnvelopeError struct {
	Code      ErrorCode      `json:"code"`
	Message   string         `json:"message"`
	Details   map[string]any `json:"details"`
	Retryable bool           `json:"retryable"`
}

type ErrorCode 

type ErrorCode string

ErrorCode classifies errors for machine consumption. 

const (
	ErrConfig          ErrorCode = "E_CONFIG"
	ErrAuth            ErrorCode = "E_AUTH"
	ErrForbidden       ErrorCode = "E_FORBIDDEN"
	ErrNotFound        ErrorCode = "E_NOT_FOUND"
	ErrConflict        ErrorCode = "E_CONFLICT"
	ErrRateLimit       ErrorCode = "E_RATE_LIMITED"
	ErrServer          ErrorCode = "E_SERVER"
	ErrValidation      ErrorCode = "E_VALIDATION"
	ErrConfirmRequired ErrorCode = "E_CONFIRMATION_REQUIRED"
	ErrCancelled       ErrorCode = "E_CANCELLED"
	ErrTimeout         ErrorCode = "E_TIMEOUT"
	ErrNetwork         ErrorCode = "E_NETWORK"
	ErrUnknown         ErrorCode = "E_UNKNOWN"
)

func ErrorCodeFromStatus 

func ErrorCodeFromStatus(statusCode int) ErrorCode

ErrorCodeFromStatus maps HTTP status codes to error codes.

type FlatBranch 

type FlatBranch struct {
	Name      string `json:"name"`
	Default   bool   `json:"default"`
	Protected bool   `json:"protected"`
	Merged    bool   `json:"merged"`
	WebURL    string `json:"webUrl,omitempty"`
	CommitID  string `json:"commitId,omitempty"`
}

FlatBranch is a token-efficient representation of a GitLab branch.

func ToFlatBranch 

func ToFlatBranch(b *api.Branch) FlatBranch

ToFlatBranch converts an api.Branch to a FlatBranch.

type FlatCommit 

type FlatCommit struct {
	ID            string `json:"id"`
	ShortID       string `json:"shortId"`
	Title         string `json:"title"`
	AuthorName    string `json:"authorName"`
	AuthoredDate  string `json:"authoredDate,omitempty"`
	CommittedDate string `json:"committedDate,omitempty"`
	WebURL        string `json:"webUrl,omitempty"`
}

FlatCommit is a token-efficient representation of a GitLab commit.

func ToFlatCommit 

func ToFlatCommit(c *api.Commit) FlatCommit

ToFlatCommit converts an api.Commit to a FlatCommit.

type FlatIssue 

type FlatIssue struct {
	IID       int    `json:"iid"`
	Title     string `json:"title"`
	State     string `json:"state"`
	Author    string `json:"author,omitempty"`
	Assignee  string `json:"assignee,omitempty"`
	Labels    string `json:"labels,omitempty"`
	Milestone string `json:"milestone,omitempty"`
	// Description carries the full issue body. It is only emitted by single-issue
	// reads (IssueDetailToMap); list output omits it for token efficiency.
	Description string `json:"description,omitempty"`
	WebURL      string `json:"webUrl,omitempty"`
}

FlatIssue is a token-efficient representation of a GitLab issue.

type FlatJob 

type FlatJob struct {
	ID         int     `json:"id"`
	Name       string  `json:"name"`
	Status     string  `json:"status"`
	Stage      string  `json:"stage,omitempty"`
	Ref        string  `json:"ref,omitempty"`
	WebURL     string  `json:"webUrl,omitempty"`
	CreatedAt  string  `json:"createdAt,omitempty"`
	StartedAt  string  `json:"startedAt,omitempty"`
	FinishedAt string  `json:"finishedAt,omitempty"`
	Duration   float64 `json:"duration,omitempty"`
	Username   string  `json:"username,omitempty"`
	PipelineID int     `json:"pipelineId,omitempty"`
}

FlatJob is a token-efficient representation of a GitLab CI job.

type FlatLabel 

type FlatLabel struct {
	ID          int    `json:"id"`
	Name        string `json:"name"`
	Color       string `json:"color"`
	Description string `json:"description,omitempty"`
	Priority    *int   `json:"priority,omitempty"`
}

FlatLabel is a token-efficient representation of a GitLab label.

type FlatMR 

type FlatMR struct {
	IID    int    `json:"iid"`
	Title  string `json:"title"`
	State  string `json:"state"`
	Source string `json:"source"`
	Target string `json:"target"`
	Author string `json:"author"`
	WebURL string `json:"webUrl"`
	Draft  bool   `json:"draft"`
	// Description carries the full MR body. It is only emitted by single-MR reads
	// (MRDetailToMap); list output omits it for token efficiency.
	Description string `json:"description,omitempty"`
}

FlatMR is a token-efficient representation of a GitLab merge request.

func ToFlatMR 

func ToFlatMR(mr *api.MergeRequest) FlatMR

ToFlatMR converts a MergeRequest to FlatMR.

type FlatMRNote 

type FlatMRNote struct {
	ID      int    `json:"id"`
	Author  string `json:"author"`
	Body    string `json:"body"`
	Created string `json:"created"`
}

FlatMRNote is a token-efficient representation of a GitLab MR note.

func ToFlatMRNote 

func ToFlatMRNote(n *api.MergeRequestNote) FlatMRNote

ToFlatMRNote converts a MergeRequestNote to FlatMRNote.

type FlatMilestone 

type FlatMilestone struct {
	ID        int    `json:"id"`
	IID       int    `json:"iid"`
	Title     string `json:"title"`
	State     string `json:"state"`
	StartDate string `json:"startDate,omitempty"`
	DueDate   string `json:"dueDate,omitempty"`
	WebURL    string `json:"webUrl,omitempty"`
}

FlatMilestone is a token-efficient representation of a GitLab milestone.

type FlatPipeline 

type FlatPipeline struct {
	ID        int    `json:"id"`
	IID       int    `json:"iid"`
	ProjectID int    `json:"projectId"`
	Ref       string `json:"ref"`
	SHA       string `json:"sha,omitempty"`
	Status    string `json:"status"`
	Source    string `json:"source,omitempty"`
	WebURL    string `json:"webUrl,omitempty"`
	CreatedAt string `json:"createdAt,omitempty"`
	UpdatedAt string `json:"updatedAt,omitempty"`
	Username  string `json:"username,omitempty"`
}

FlatPipeline is a token-efficient representation of a GitLab pipeline.

type FlatProject 

type FlatProject struct {
	ID                int    `json:"id"`
	PathWithNamespace string `json:"pathWithNamespace"`
	Name              string `json:"name"`
	Visibility        string `json:"visibility"`
	WebURL            string `json:"webUrl"`
	DefaultBranch     string `json:"defaultBranch"`
}

FlatProject is a token-efficient representation of a GitLab project.

func ToFlatProject 

func ToFlatProject(p *api.Project) FlatProject

ToFlatProject converts an api.Project to FlatProject.

type FlatProjectMember 

type FlatProjectMember struct {
	ID          int    `json:"id"`
	Username    string `json:"username"`
	Name        string `json:"name"`
	State       string `json:"state"`
	AccessLevel int    `json:"accessLevel"`
}

FlatProjectMember is a token-efficient representation of a project member.

func ToFlatProjectMember 

func ToFlatProjectMember(m *api.ProjectMember) FlatProjectMember

ToFlatProjectMember converts an api.ProjectMember to FlatProjectMember.

type FlatRelease 

type FlatRelease struct {
	TagName     string `json:"tagName"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	CreatedAt   string `json:"createdAt,omitempty"`
	ReleasedAt  string `json:"releasedAt,omitempty"`
	Author      string `json:"author,omitempty"`
	CommitID    string `json:"commitId,omitempty"`
	AssetCount  int    `json:"assetCount"`
}

FlatRelease is a token-efficient representation of a GitLab release.

func ToFlatRelease 

func ToFlatRelease(r *api.Release) FlatRelease

ToFlatRelease converts an api.Release to a FlatRelease.

type FlatSearchBlob 

type FlatSearchBlob struct {
	Filename  string `json:"filename"`
	Path      string `json:"path"`
	Ref       string `json:"ref"`
	StartLine int    `json:"startLine"`
	Data      string `json:"data"`
	ProjectID int    `json:"projectId"`
}

FlatSearchBlob is a slim code search result.

func ToFlatSearchBlob 

func ToFlatSearchBlob(b *api.SearchBlob) FlatSearchBlob

ToFlatSearchBlob converts api.SearchBlob to FlatSearchBlob.

type FlatSearchCommit 

type FlatSearchCommit struct {
	ID         string `json:"id"`
	ShortID    string `json:"shortId"`
	Title      string `json:"title"`
	AuthorName string `json:"authorName"`
	CreatedAt  string `json:"createdAt"`
	WebURL     string `json:"webUrl"`
}

FlatSearchCommit is a slim commit search result.

func ToFlatSearchCommit 

func ToFlatSearchCommit(c *api.SearchCommit) FlatSearchCommit

ToFlatSearchCommit converts api.SearchCommit to FlatSearchCommit.

type FlatSearchIssue 

type FlatSearchIssue struct {
	ID        int    `json:"id"`
	IID       int    `json:"iid"`
	Title     string `json:"title"`
	State     string `json:"state"`
	WebURL    string `json:"webUrl"`
	ProjectID int    `json:"projectId"`
}

FlatSearchIssue is a slim search result for an issue.

func ToFlatSearchIssue 

func ToFlatSearchIssue(i *api.SearchIssue) FlatSearchIssue

ToFlatSearchIssue converts api.SearchIssue to FlatSearchIssue.

type FlatSearchMR 

type FlatSearchMR struct {
	ID        int    `json:"id"`
	IID       int    `json:"iid"`
	Title     string `json:"title"`
	State     string `json:"state"`
	WebURL    string `json:"webUrl"`
	ProjectID int    `json:"projectId"`
}

FlatSearchMR is a slim search result for a merge request.

func ToFlatSearchMR 

func ToFlatSearchMR(m *api.SearchMR) FlatSearchMR

ToFlatSearchMR converts api.SearchMR to FlatSearchMR.

type FlatSearchProject 

type FlatSearchProject struct {
	ID                int    `json:"id"`
	Name              string `json:"name"`
	PathWithNamespace string `json:"pathWithNamespace"`
	WebURL            string `json:"webUrl"`
	Visibility        string `json:"visibility"`
}

FlatSearchProject is a slim search result for a project.

func ToFlatSearchProject 

func ToFlatSearchProject(p *api.SearchProject) FlatSearchProject

ToFlatSearchProject converts api.SearchProject to FlatSearchProject.

type FlatTreeEntry 

type FlatTreeEntry struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	Type string `json:"type"`
	Path string `json:"path"`
	Mode string `json:"mode,omitempty"`
}

FlatTreeEntry is a token-efficient representation of a GitLab tree entry.

func ToFlatTreeEntry 

func ToFlatTreeEntry(e *api.TreeEntry) FlatTreeEntry

ToFlatTreeEntry converts an api.TreeEntry to a FlatTreeEntry.

type FlatUser 

type FlatUser struct {
	ID       int    `json:"id"`
	Username string `json:"username"`
	Name     string `json:"name,omitempty"`
	Email    string `json:"email,omitempty"`
	State    string `json:"state,omitempty"`
	WebURL   string `json:"webUrl,omitempty"`
}

FlatUser is a token-efficient representation of a GitLab user.

type FlatVariable 

type FlatVariable struct {
	Key         string `json:"key"`
	Type        string `json:"type"`
	Protected   bool   `json:"protected"`
	Masked      bool   `json:"masked"`
	Raw         bool   `json:"raw"`
	EnvScope    string `json:"envScope"`
	Description string `json:"description,omitempty"`
}

FlatVariable is a token-efficient representation of a GitLab CI/CD variable. The Value field is intentionally EXCLUDED to prevent accidental secret leakage in table output. Use FlatVariableWithValue only when --json is explicitly requested.

func ToFlatVariable 

func ToFlatVariable(v *api.Variable) FlatVariable

ToFlatVariable converts an api.Variable to FlatVariable (no value).

type FlatVariableWithValue 

type FlatVariableWithValue struct {
	Key         string `json:"key"`
	Value       string `json:"value"`
	Type        string `json:"type"`
	Protected   bool   `json:"protected"`
	Masked      bool   `json:"masked"`
	Raw         bool   `json:"raw"`
	EnvScope    string `json:"envScope"`
	Description string `json:"description,omitempty"`
}

FlatVariableWithValue includes the secret value — only for --json output.

func ToFlatVariableWithValue 

func ToFlatVariableWithValue(v *api.Variable) FlatVariableWithValue

ToFlatVariableWithValue converts an api.Variable to FlatVariableWithValue (includes value).

type ListEnvelope 

type ListEnvelope struct {
	Items []map[string]any `json:"items"`
	ListMeta
}

ListEnvelope is the standard JSON shape for list commands.

func NewListEnvelope 

func NewListEnvelope(items []map[string]any, meta ListMeta) ListEnvelope

NewListEnvelope builds a list response with projected items.

type ListMeta 

type ListMeta struct {
	Count   int  `json:"count"`
	Limit   int  `json:"limit"`
	Page    int  `json:"page,omitempty"`
	Total   int  `json:"total,omitempty"`
	HasMore bool `json:"hasMore"`
	All     bool `json:"all,omitempty"`
}

ListMeta describes pagination for list command JSON output.

type Meta added in v1.2.0 

type Meta struct {
	DurationMS int64 `json:"duration_ms"`
}

Source Files

View all Source files

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.