cmdutil

Documentation

Overview

Package cmdutil provides shared utilities for CLI commands.

Index

• func CategoryOf(err error) errs.Category
• func CheckOK(resp string) error
• func CheckResponse(resp string) error
• func DoAPI(ctx context.Context, endpoint, method, body string, debug bool) (string, error)
• func ExtractData(resp string) string
• func HandleCommandError(stderr io.Writer, err error, jsonMode bool) error
• func IsClassified(err error) bool
• func JSONString(v any) string
• func ResolveBaseURL(baseURLArg string) string
• func WriteDryRun(w io.Writer, preview RequestPreview, jsonMode bool) error
• type RequestPreview
  • func NewRequestPreview(method, endpoint string, body interface{}) RequestPreview

Functions

func CategoryOf

func CategoryOf(err error) errs.Category

CategoryOf returns the errs.Category for any error the CLI may produce. This is the single dispatch point used by HandleCommandError and main().

func CheckOK

func CheckOK(resp string) error

CheckOK is an alias for CheckResponse kept for backward compatibility.

func CheckResponse

func CheckResponse(resp string) error

CheckResponse is the single entry-point for validating any API response. It performs two checks in order:

1. Outer envelope: {"code":N,"msg":"..."} — non-200/non-0 code signals failure.
2. Partial-success results: {"data":{"results":[{"error":{"code":N,...}}]}} — batch endpoints return HTTP 200 even when individual items fail; this detects per-item errors and surfaces them as a combined error message.

All mutation commands should call CheckResponse instead of CheckOK.

func DoAPI

func DoAPI(ctx context.Context, endpoint, method, body string, debug bool) (string, error)

DoAPI loads the profile, creates a client, and calls the API.

func ExtractData

func ExtractData(resp string) string

ExtractData unwraps the standard backend envelope {"code":N,"msg":"...","data":{...}} and returns the raw JSON of the "data" field. If the response has no "data" field the original string is returned unchanged, so callers that receive a flat response still work correctly.

func HandleCommandError

func HandleCommandError(stderr io.Writer, err error, jsonMode bool) error

HandleCommandError writes a structured error to stderr and returns the error unchanged so the caller can propagate it up the Cobra RunE chain.

In --json mode every error path emits a single unified JSON envelope:

{"ok":false,"error":{"type":"authentication","code":401,"message":"...","hint":"..."}}

In plain mode a human-readable ✗ message with optional hint is printed.

NOTE: callers must NOT also print the error themselves — this function is the single point of stderr output. main() only sets the exit code, it does not print again.

func IsClassified

func IsClassified(err error) bool

IsClassified reports whether an error already belongs to the CLI's stable error taxonomy. CategoryAPI alone cannot distinguish a real APIError from an unclassified Cobra error, so main uses this check before selecting fallback behavior.

func JSONString

func JSONString(v any) string

JSONString builds a JSON string from a value, or returns "{}" on failure.

func ResolveBaseURL

func ResolveBaseURL(baseURLArg string) string

ResolveBaseURL resolves the effective base URL from arg, env, or config.

func WriteDryRun

func WriteDryRun(w io.Writer, preview RequestPreview, jsonMode bool) error

WriteDryRun emits the common request-preview contract. JSON mode always returns a success envelope; plain mode carries an explicit marker on stdout.

Types

type RequestPreview

type RequestPreview struct {
	Method string      `json:"method"`
	URL    string      `json:"url"`
	Body   interface{} `json:"body,omitempty"`
}

RequestPreview is the stable representation of an HTTP request that would be sent by a dry-run. Credentials and headers are intentionally excluded.

func NewRequestPreview

func NewRequestPreview(method, endpoint string, body interface{}) RequestPreview

NewRequestPreview builds a credential-free preview using the same base URL resolution as real API calls.