cmdutil

package
v0.12.0 Latest Latest
Warning

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

 Go to latest Published: Aug 12, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package cmdutil provides utilities for command implementation

Index

Constants

View Source 
const (
	ExitSuccess  = 0
	ExitError    = 1
	ExitUsage    = 2
	ExitNotFound = 3
	ExitAuth     = 4
	ExitConflict = 5
)
View Source 
const FlagEnumAnnotation = "gc.enum"
View Source 
const TopicAnnotation = "gc.topic"

Variables

View Source 
var ErrLossyPowerShellStdin = errors.New("lossy Windows PowerShell stdin")

ErrLossyPowerShellStdin is returned when Windows PowerShell appears to have replaced non-ASCII stdin text with question marks before the CLI could read it.

View Source 
var ErrSecretDetected = fmt.Errorf("content contains secret")

ErrSecretDetected is returned when ScanContentForSecrets detects a secret.

View Source 
var StandardTopics = []string{
	"auth",
	"commits",
	"issues",
	"labels",
	"milestones",
	"precommit",
	"pull-requests",
	"releases",
	"repo",
}

StandardTopics is the list of standard topic categories.

Functions

func AddFormatFlag added in v0.3.10 

func AddFormatFlag(cmd *cobra.Command, target *string)

AddFormatFlag adds a consistent format flag to a command.

func AddJSONFlag added in v0.3.7 

func AddJSONFlag(cmd *cobra.Command, target *bool)

AddJSONFlag adds a consistent JSON output flag to a command.

func AddTemplateFlag added in v0.3.10 

func AddTemplateFlag(cmd *cobra.Command, target *string)

AddTemplateFlag adds a consistent template flag to a command.

func AddTimeFormatFlag added in v0.3.10 

func AddTimeFormatFlag(cmd *cobra.Command, target *string)

AddTimeFormatFlag adds a consistent time-format flag to a command.

func AuthenticatedClient added in v0.4.0 

func AuthenticatedClient(httpClient *http.Client) (*api.Client, error)

AuthenticatedClient creates an API client using the configured default host and active token. Environment tokens keep their existing priority.

func AuthenticatedClientFromFactory added in v0.4.0 

func AuthenticatedClientFromFactory(httpClient func() (*http.Client, error)) (*api.Client, error)

AuthenticatedClientFromFactory creates an authenticated API client from the command factory dependencies.

func ConfirmOrAbort added in v0.3.7 

func ConfirmOrAbort(opts ConfirmOptions) error

ConfirmOrAbort enforces a shared confirmation flow.

func ConfirmTokenDisclosure added in v0.7.0 

func ConfirmTokenDisclosure(ioStreams *iostreams.IOStreams, hostname string) error

ConfirmTokenDisclosure gates commands that print a full authentication token.

func DecodeUserText added in v0.5.8 

func DecodeUserText(content []byte) string

DecodeUserText decodes text accepted from user-facing files or stdin.

func DefaultToken added in v0.7.0 

func DefaultToken() string

DefaultToken returns the active token, checking environment variables first, then falling back to the configured token file.

func ExitCode added in v0.3.7 

func ExitCode(err error) int

ExitCode maps a command error to a stable process exit code.

func FormatAPIID added in v0.3.7 

func FormatAPIID(id interface{}) string

FormatAPIID normalizes API IDs that may arrive as strings or JSON numbers.

func NewAuthError added in v0.3.7 

func NewAuthError(message string) error

func NewCLIError added in v0.3.7 

func NewCLIError(code int, message string, cause error) error

NewCLIError creates a CLIError with a stable exit code.

func NewConflictError added in v0.5.0 

func NewConflictError(message string) error

func NewNotFoundError added in v0.3.7 

func NewNotFoundError(message string, cause error) error

func NewUsageError added in v0.3.7 

func NewUsageError(message string) error

func NormalizeLabels added in v0.11.0 

func NormalizeLabels(labels []string) []string

NormalizeLabels parses a slice of label names (typically from a comma-separated --add/--labels flag or cobra StringSlice) into a clean list: splits on comma, trims whitespace, drops empty entries, and de-duplicates. Splitting is idempotent for already-split input, so it is safe whether cobra pre-split the value or not. Order of first occurrence is preserved.

func ParseRepo added in v0.3.7 

func ParseRepo(repo string) (string, string, error)

ParseRepo parses a repository reference and returns the owner and repository name. It supports owner/repo, HTTPS URLs, and SSH URLs.

func ReadBody added in v0.7.0 

func ReadBody(body, bodyFile string, stdin io.Reader) (string, error)

ReadBody resolves the body text from --body and --body-file flags. body and bodyFile are the raw flag values; stdin is used when bodyFile == "-". It returns an error when both body and bodyFile are set.

func ReadText added in v0.5.8 

func ReadText(r io.Reader) (string, error)

ReadText reads user-provided text from a stream.

func ReadTextFile added in v0.5.3 

func ReadTextFile(path string) (string, error)

ReadTextFile reads a user-provided text file and strips a UTF-8 BOM when present.

func ReadTextFromFlag added in v0.5.9 

func ReadTextFromFlag(r io.Reader, flagName string) (string, error)

ReadTextFromFlag reads stdin text for an explicit file flag such as --body-file - or --comment-file - and rejects input that Windows PowerShell appears to have already corrupted before the CLI could decode it.

func ResolvePRURL added in v0.5.0 

func ResolvePRURL(htmlURL, owner, repo string, number int) string

ResolvePRURL returns the PR URL with fallback logic. If the API-provided URL is empty, it constructs one from owner/repo/number.

func ResolveRepo added in v0.3.7 

func ResolveRepo(repo string, baseRepo func() (string, error)) (string, error)

ResolveRepo returns the explicit repository when provided, otherwise tries to infer it from the current git repository.

func ScanContentForSecrets added in v0.7.0 

func ScanContentForSecrets(content string) error

ScanContentForSecrets scans content for the current GC_TOKEN/GITCODE_TOKEN environment variable value. It is called before submitting user-provided body/comment content to the GitCode API to prevent AI agents (or humans) from accidentally leaking the current GitCode credential into issues, PRs, comments, or releases.

GitCode tokens have no fixed prefix (unlike GitHub's ghp_), so pattern matching is not viable; the only reliable check is whether the current token value appears in the content. This is the highest-value defense against the common AI mistake of pasting $GC_TOKEN into an issue body.

On detection, returns an error. The content is NOT modified (no redaction); submission is refused so the caller can surface the error before any API call is made.

func SetFlagEnum added in v0.4.0 

func SetFlagEnum(cmd *cobra.Command, name string, values ...string) error

SetFlagEnum records a stable enum set for schema/export consumers. It returns an error (e.g. when the flag is not registered on the command) instead of panicking, so callers can decide how to handle it.

func SetFlagEnumOrWarn added in v0.11.0 

func SetFlagEnumOrWarn(cmd *cobra.Command, name string, values ...string)

SetFlagEnumOrWarn records a stable enum set for schema/export consumers and degrades an annotation failure to a stderr warning instead of crashing the process. Use this from command constructors (NewCmd*) whose signature (*cobra.Command) cannot propagate an error; the annotation is non-functional metadata for schema/export, so a missing enum does not break the command.

func SetTopicAnnotation added in v0.4.0 

func SetTopicAnnotation(cmd *cobra.Command, topic string)

SetTopicAnnotation adds a topic annotation to a command.

func WrapNotFound added in v0.5.0 

func WrapNotFound(err error, format string, args ...interface{}) error

WrapNotFound wraps an error as NotFoundError if it's a 404 API error. Returns the original error if it's not a 404. Usage: return cmdutil.WrapNotFound(err, "issue #%d not found in %s/%s", number, owner, repo)

func WriteJSON added in v0.3.7 

func WriteJSON(w io.Writer, value interface{}) error

WriteJSON writes indented JSON to the target writer.

A nil slice is normalized to an empty slice so list commands emit `[]` instead of `null` when there are no results, keeping --json output stable and consumable by scripts and agents (see spec/foundations/agent-friendly-cli.md).

Only the top-level value is normalized. A nil value with no concrete type, a pointer to a nil slice (e.g. *[]T), and nil slice fields nested inside a struct are left untouched and still encode as `null`; commands that rely on such fields (e.g. pr view --json emitting "comments": null) are unaffected.

Types

type CLIError added in v0.3.7 

type CLIError struct {
	Code    int
	Message string
	Cause   error
}

CLIError represents a stable CLI-facing error with an exit code.

func (*CLIError) Error added in v0.3.7 

func (e *CLIError) Error() string

func (*CLIError) Unwrap added in v0.3.7 

func (e *CLIError) Unwrap() error

type ConfirmOptions added in v0.3.7 

type ConfirmOptions struct {
	IO       *iostreams.IOStreams
	Yes      bool
	Expected string
	Prompt   string
}

ConfirmOptions controls destructive-action confirmation prompts.

type Factory 

type Factory struct {
	IOStreams  *iostreams.IOStreams
	HttpClient func() (*http.Client, error)
	Config     func() (config.Config, error)
	BaseRepo   func() (string, error)
	Branch     func() (string, error)
}

Factory provides dependencies for commands

func NewFactory 

func NewFactory() *Factory

NewFactory creates a new Factory with default settings

func TestFactory 

func TestFactory() *Factory

TestFactory creates a Factory for testing

Source Files

  • auth.go
  • confirm.go
  • errors.go
  • factory.go
  • flag_annotations.go
  • format.go
  • output.go
  • repo.go
  • secret_scan.go
  • text_file.go
  • token_confirm.go

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.