go.step.sm/cli-utils v0.9.0: validate CLI arguments, flags, and file errors using errs

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: validate CLI arguments, flags, and file errors using errs
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/go.step.sm/cli-utils@v0.9.0
Demonstrate these symbols/APIs:
  - go.step.sm/cli-utils/errs.FileError
  - go.step.sm/cli-utils/errs.IncompatibleFlag
  - go.step.sm/cli-utils/errs.MutuallyExclusiveFlags
  - go.step.sm/cli-utils/errs.NumberOfArguments
  - go.step.sm/cli-utils/errs.RequiredFlag

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:ce43506cd1e9c015e2d1a4c92869e9ceb6ee0e8e8eb22e331b5f1eca6000a8f3","contract":["NumberOfArguments returns nil when the exact number of positional arguments is provided","NumberOfArguments returns an error when too few or too many arguments are provided","RequiredFlag formats error message specifying command and missing flag","MutuallyExclusiveFlags reports conflict between two incompatible flags","IncompatibleFlag reports error when a flag is used with an unsupported value","FileError formats PathError details and handles nil errors"],"goal":"validate CLI arguments, flags, and file errors using errs","kind":"HOW","packages":["pkg:golang/go.step.sm/cli-utils@v0.9.0"],"schemaVersion":1,"symbols":["go.step.sm/cli-utils/errs.FileError","go.step.sm/cli-utils/errs.IncompatibleFlag","go.step.sm/cli-utils/errs.MutuallyExclusiveFlags","go.step.sm/cli-utils/errs.NumberOfArguments","go.step.sm/cli-utils/errs.RequiredFlag"]},"contractCommand":["go","test","./..."],"environment":{"arch":"amd64","distro":"ubuntu","ecosystem":"golang","language":"go","languageVersion":"1.26","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","packageManagerVersion":"1.26.6","runtime":"go","runtimeVersion":"1.26.6","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/go.step.sm/cli-utils@v0.9.0"],"schemaVersion":1,"subject":"pkg:golang/go.step.sm/cli-utils@v0.9.0","symbols":["go.step.sm/cli-utils/errs.FileError","go.step.sm/cli-utils/errs.IncompatibleFlag","go.step.sm/cli-utils/errs.MutuallyExclusiveFlags","go.step.sm/cli-utils/errs.NumberOfArguments","go.step.sm/cli-utils/errs.RequiredFlag"],"verifierAdapter":"golang@1"}

module sample

go 1.26.6

require (
	github.com/urfave/cli v1.22.14
	go.step.sm/cli-utils v0.9.0
)

require (
	github.com/cpuguy83/go-md2man/v2 v2.0.2 // indirect
	github.com/pkg/errors v0.9.1 // indirect
	github.com/russross/blackfriday/v2 v2.1.0 // indirect
)

github.com/BurntSushi/toml v1.3.2/go.mod h1:CxXYINrC8qIiEnFrOxCa7Jy5BFHlXnUU2pbicEuybxQ=
github.com/cpuguy83/go-md2man/v2 v2.0.2 h1:p1EgwI/C7NhT0JmVkwCD2ZBK8j4aeHQX2pMHHBfMQ6w=
github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
github.com/urfave/cli v1.22.14 h1:ebbhrRiGK2i4naQJr+1Xj92HXZCrK7MsyTS/ob3HnAk=
github.com/urfave/cli v1.22.14/go.mod h1:X0eDS6pD6Exaclxm99NJ3FiCDRED7vIHpx2mDOHLvkA=
go.step.sm/cli-utils v0.9.0 h1:55jYcsQbnArNqepZyAwcato6Zy2MoZDRkWW+jF+aPfQ=
go.step.sm/cli-utils v0.9.0/go.mod h1:Y/CRoWl1FVR9j+7PnAewufAwKmBOTzR6l9+7EYGAnp8=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

package sample

import (
	"github.com/urfave/cli"
	"go.step.sm/cli-utils/errs"
)

// ValidateArgCount validates that the CLI context has exactly the expected number of arguments.
func ValidateArgCount(ctx *cli.Context, expected int) error {
	return errs.NumberOfArguments(ctx, expected)
}

// CheckRequiredFlag returns an error indicating that a mandatory flag is missing.
func CheckRequiredFlag(ctx *cli.Context, flagName string) error {
	return errs.RequiredFlag(ctx, flagName)
}

// CheckExclusiveFlags returns an error indicating two flags cannot be used together.
func CheckExclusiveFlags(ctx *cli.Context, flag1, flag2 string) error {
	return errs.MutuallyExclusiveFlags(ctx, flag1, flag2)
}

// CheckIncompatibleFlag returns an error indicating a flag cannot be used with a specific value.
func CheckIncompatibleFlag(ctx *cli.Context, flag, value string) error {
	return errs.IncompatibleFlag(ctx, flag, value)
}

// WrapFileError wraps OS file operation errors with formatted context.
func WrapFileError(err error, filename string) error {
	return errs.FileError(err, filename)
}

{
  "schemaVersion": 1,
  "goal": "validate CLI arguments, flags, and file errors using errs",
  "kind": "HOW",
  "packages": [
    "pkg:golang/go.step.sm/cli-utils@v0.9.0"
  ],
  "symbols": [
    "go.step.sm/cli-utils/errs.FileError",
    "go.step.sm/cli-utils/errs.IncompatibleFlag",
    "go.step.sm/cli-utils/errs.MutuallyExclusiveFlags",
    "go.step.sm/cli-utils/errs.NumberOfArguments",
    "go.step.sm/cli-utils/errs.RequiredFlag"
  ]
}

package test

import (
	"flag"
	"io"
	"os"
	"path/filepath"
	"strings"
	"testing"

	"github.com/urfave/cli"
	"sample"
)

func newTestCLI(t *testing.T, args ...string) *cli.Context {
	t.Helper()

	fs := flag.NewFlagSet("cmd", flag.ContinueOnError)
	if err := fs.Parse(args); err != nil {
		t.Fatalf("flag parse error: %v", err)
	}

	app := cli.NewApp()
	app.Name = "app"
	app.HelpName = "app"
	app.Writer = io.Discard
	app.ErrWriter = io.Discard

	ctx := cli.NewContext(app, fs, nil)
	ctx.Command = cli.Command{
		Name: "cmd",
	}

	return ctx
}

func TestContract_NumberOfArguments_Match(t *testing.T) {
	ctx := newTestCLI(t, "arg1", "arg2")

	if err := sample.ValidateArgCount(ctx, 2); err != nil {
		t.Fatalf("expected nil error for exact match, got: %v", err)
	}
}

func TestContract_NumberOfArguments_Mismatch(t *testing.T) {
	ctx := newTestCLI(t, "arg1", "arg2")

	tooFewErr := sample.ValidateArgCount(ctx, 3)
	if tooFewErr == nil {
		t.Fatal("expected error when fewer arguments provided than required")
	}
	if !strings.Contains(tooFewErr.Error(), "not enough positional arguments") {
		t.Errorf("expected 'not enough positional arguments' in error, got: %v", tooFewErr)
	}

	tooManyErr := sample.ValidateArgCount(ctx, 1)
	if tooManyErr == nil {
		t.Fatal("expected error when more arguments provided than required")
	}
	if !strings.Contains(tooManyErr.Error(), "too many positional arguments") {
		t.Errorf("expected 'too many positional arguments' in error, got: %v", tooManyErr)
	}
}

func TestContract_RequiredFlag(t *testing.T) {
	ctx := newTestCLI(t)

	err := sample.CheckRequiredFlag(ctx, "config")
	if err == nil {
		t.Fatal("expected error for missing required flag")
	}

	expected := "'app cmd' requires the '--config' flag"
	if err.Error() != expected {
		t.Errorf("expected %q, got %q", expected, err.Error())
	}
}

func TestContract_MutuallyExclusiveFlags(t *testing.T) {
	ctx := newTestCLI(t)

	err := sample.CheckExclusiveFlags(ctx, "json", "yaml")
	if err == nil {
		t.Fatal("expected error for mutually exclusive flags")
	}

	expected := "flag '--json' and flag '--yaml' are mutually exclusive"
	if err.Error() != expected {
		t.Errorf("expected %q, got %q", expected, err.Error())
	}
}

func TestContract_IncompatibleFlag(t *testing.T) {
	ctx := newTestCLI(t)

	err := sample.CheckIncompatibleFlag(ctx, "format", "xml")
	if err == nil {
		t.Fatal("expected error for incompatible flag value")
	}

	expected := "flag '--format' is incompatible with 'xml'"
	if err.Error() != expected {
		t.Errorf("expected %q, got %q", expected, err.Error())
	}
}

func TestContract_FileError(t *testing.T) {
	if err := sample.WrapFileError(nil, "somefile.txt"); err != nil {
		t.Fatalf("expected nil for nil error, got: %v", err)
	}

	tmpDir := t.TempDir()
	nonExistentPath := filepath.Join(tmpDir, "missing.txt")
	_, readErr := os.ReadFile(nonExistentPath)
	if readErr == nil {
		t.Fatal("expected ReadFile to fail for non-existent path")
	}

	wrapped := sample.WrapFileError(readErr, nonExistentPath)
	if wrapped == nil {
		t.Fatal("expected non-nil wrapped error")
	}

	if !strings.Contains(wrapped.Error(), "open ") || !strings.Contains(wrapped.Error(), "failed") {
		t.Errorf("expected formatted PathError in error message, got: %v", wrapped)
	}
}