breaking: remove deprecated flags in v3 #1059

@dangrondahl

Summary

We have 9 deprecated flag registrations in the CLI and have never removed one. The
oldest has been deprecated for over 3 years. pflag's MarkDeprecated sets
Hidden = true, so all of them are invisible in --help and in the reference docs
while continuing to work - effectively a permanent, undocumented surface.

Current release is v2.36.1. This issue proposes removing them all in v3.0.0.

They are not uniform: some are dead no-ops, some are aliases of a live flag, and two
still send data to the API. The categories carry different risk and could ship as
separate slices.

Category A - dead no-ops (safest)

The flag parses into a struct field that nothing reads. Removing them cannot change
behaviour for anyone; the flag already does nothing.

Flag	Command	Dead field	Deprecated
--function-version	snapshot lambda	o.functionVersion (snapshotLambda.go:81)	2023年06月09日
--service-name, -s	snapshot ecs	o.serviceName (snapshotECS.go:101)	2024年10月08日
--registry-provider	all commands via addFingerprintFlags	o.registryProvider (fingerprint.go:81)	2024年12月10日

--registry-provider is worth calling out: it is registered in addFingerprintFlags
(flags.go:23), which is reached from fingerprint, assert artifact,
allow artifact, report artifact, attest artifact, and every attest * command
via the shared attestation flags at flags.go:121. ValidateRegistryFlags
(cli_utils.go:519) does not reference it. Its help text at root.go:211 is already
prefixed [deprecated].

Category B - aliases of a live flag

Both names write to the same destination variable, so the replacement is exact.

Flag	Command	Alias of	Deprecated
--cluster, -C	snapshot ecs	--clusters (o.clustersFilter.IncludeNames)	2024年10月08日
--function-name	snapshot lambda	--function-names (o.filter.IncludeNames)	2023年06月09日
--e, -e	fingerprint	--exclude / -x (o.excludePaths)	2023年09月01日
--e, -e	snapshot server	--exclude / -x (o.excludePaths)	2023年09月01日

Removal also means pruning the MuXRequiredFlags lists that name them:
snapshotECS.go:122,130 (cluster), snapshotECS.go:158 (service-name), and the
two lambda lists at snapshotLambda.go:105,117 (function-name).

Category C - still sent to the API (needs a decision)

Flag	Command	Behaviour
--visibility	create flow	sets payload.Visibility, sent as visibility when explicitly passed
--require-provenance	create environment	sets payload.RequireProvenance, sent when passed

--visibility is a genuine blocker to blind removal. The comment at
createFlow.go:50-52 states it is sent only when explicitly passed "so that older
instances that still [require it]" keep working. If self-hosted or lagging instances
still require visibility on flow creation, removing the flag removes their only way
to supply it. This needs confirming with the server team before it goes in v3.0.0 -
it may need to outlive the others.

--require-provenance is cleaner: the API's own CreateEnvironmentPutInput schema
marks require_provenance deprecated with "use policies instead", so the field is
going away server-side regardless. Remove the flag and the RequireProvenance payload
field together.

Removal checklist

• Delete the flag registrations, the backing struct fields, and the DeprecateFlags /
  MarkDeprecated calls.
• Delete the now-unused help-text constants in root.go: functionVersionFlag,
  ecsServiceFlag, ecsClusterFlag, functionNameFlag, registryProviderFlag,
  visibilityFlag, requireProvenanceFlag. Leave excludePathsFlag - shared with the
  surviving --exclude.
• Prune the MuXRequiredFlags entries listed above.
• DeprecateFlags (cli_utils.go:296) becomes unused if every call site goes. Keep it
  • it is the right helper for the next deprecation - but make lint may flag it.
• Tests asserting the deprecation warnings must be updated or dropped:
  snapshotLambda_test.go:70,90,101, fingerprint_test.go:96,101,
  createFlow_test.go:29,78, createEnvironment_test.go:54,59. Several assert the
  warning text in golden, so they will fail loudly - good.
• Add tests asserting the removed flags now produce unknown flag errors.
• No docs step needed: client_reference is regenerated from the released binary by
  kosli-dev/docs on the cli-release dispatch (release.yml:261).

Freed shorthands - handle with care

Removal frees -C (--cluster), -s (--service-name), and -e (--e, on two
commands). Reusing any of these for a new flag later would silently change the meaning
of a still-circulating invocation rather than erroring. Suggest we treat them as
reserved rather than immediately reusable.

Suggested slicing

1. Category A - pure deletion, no behaviour change, no decision needed.
2. Category B - deletion plus MuXRequiredFlags pruning.
3. --require-provenance - with the payload field.
4. --visibility - only after confirming no supported instance still needs it.

Related

• The docs-visibility side of this is a separate discussion (deprecated flags are
  absent from docs.kosli.com entirely; docgen/helpers.go:69 has an unreachable
  (DEPRECATED: ...) branch because of the Hidden check at line 22).
• --include-scaling is being deprecated separately following the API change; if that
  lands, it joins this list rather than this one.

Feature