Add AI-agent help text to application commands

[ehl-jf]

Summary

Adds AI-agent-oriented help text (AIDescription) so commands render richer help when JFROG_CLI_AI_HELP is truthy or an AI agent is auto-detected. Empty AIDescription falls back to Description; human-mode output is unchanged.

Scope: 13 components.Command literals across apptrust/commands/* + 1 namespace in cli/cli.go.

Dependency on jfrog-cli-core

jfrog-cli-core's JGC-473 PR (#1563) has MERGED. This PR's go.mod now requires the merged core master pseudo-version v2.60.1-0.20260601130310-8d52a530da18 directly — no temporary replace directive. Ready to merge on its own.

Linked

• jfrog-cli-core (merged): Add AIDescription field and AI-mode help resolver jfrog-cli-core#1563
• umbrella: Add AI context description to commands jfrog-cli#3503

[shayshim]

Bug: --overwrite-strategy=fail is not a valid value

Two AIDescription examples reference --overwrite-strategy=fail, which the CLI will reject at runtime:

• promote_app_version_cmd.go: ... PROD --overwrite-strategy=fail --dry-run
• release_app_version_cmd.go: ... 1.0.0 --overwrite-strategy=fail

The only valid values, as defined in apptrust/model/promote_app_version_request.go and enforced by ParseOverwriteStrategy → ValidateEnumFlag at runtime, are:

disabled   – skip conflicting artifacts
latest     – overwrite only if the source is newer
all        – overwrite unconditionally

An AI agent following these examples would generate a command that immediately errors out. Suggest replacing fail with disabled (the most conservative choice) in both examples.

[shayshim]

Style / Accuracy notes (non-blocking but worth fixing before merge)

An AI agent treats AIDescription as ground truth, so inaccurate claims get amplified into confidently-wrong advice.

---

1. version-create — SemVer claim is not enforced by the CLI

Gotcha: The version argument must be a valid SemVer string.

The CLI does not validate SemVer at parse time — validateCreateAppVersionContext only checks argument count and source flags. The argument description says "in SemVer format" as guidance, but nothing rejects 2024.1, v1, or other non-SemVer strings. An AI following this gotcha would refuse to generate commands with perfectly legal version strings.

Suggest: change to "The version should follow SemVer convention (e.g. 1.0.0, 1.2.3-rc1); the CLI does not validate the format but the platform may reject non-conforming values."

---

2. version-delete — misleading rollback suggestion

Gotcha: Deletion is irreversible; consider version-rollback first if you only want to undo a promotion.

This is confusing because rollback undoes artifact placement from a stage — it is not an alternative to deletion. A reader (human or AI) could interpret this as "rollback is a softer version of delete", which is wrong. Rollback and delete are orthogonal operations.

Suggest: "Deletion is irreversible and removes the version record itself. To undo a promotion without deleting the version, use version-rollback instead."

---

3. version-update — properties format not explained in Gotchas

The example uses:

--properties="env=prod;owner=team-a,team-b"

The code (ParseListPropertiesFlag) confirms: semicolons separate key-value pairs, commas separate multiple values for the same key. This dual-separator format is non-obvious and easy to get wrong, but the Gotchas section doesn't mention it.

Suggest adding: "--properties uses semicolons to separate key=value pairs and commas to separate multiple values for a single key: key1=v1,v2;key2=v3."

---

4. app-update — owner replacement behavior should be verified

Gotcha: --user-owners and --group-owners replace the full owner list each time they are specified.

The update command code doesn't appear to contain any owner-related logic (no UserOwner/GroupOwner field handling visible in the command file). Please confirm this replace-vs-merge behavior is actually implemented and that the claim is accurate — if it's wrong, it's a high-impact footgun for an AI agent.

[ehl-jf]

Thanks @shayshim — really valuable review, especially the point about agents treating AIDescription as ground truth. Applied all of it in baaffa1:

Bug — --overwrite-strategy=fail: fixed in both promote_app_version_cmd.go and release_app_version_cmd.go → --overwrite-strategy=disabled. Confirmed against model.OverwriteStrategyValues (disabled/latest/all) — fail would indeed error at runtime.

1. version-create SemVer: agreed — validateCreateAppVersionContext only checks arg count + source flags, no SemVer validation. Reworded to: "The version should follow SemVer convention (e.g. 1.0.0, 1.2.3-rc1); the CLI does not validate the format, but the platform may reject non-conforming values."

2. version-delete rollback: agreed it conflated two orthogonal operations. Reworded to make clear rollback undoes a promotion and is not a softer delete.

3. version-update properties: good catch — confirmed ParseListPropertiesFlag splits ; for pairs and , for values. Added a gotcha spelling out the dual separator (key1=v1,v2;key2=v3).

4. app-update owners: one clarification — the --user-owners/--group-owners flags are wired for app-update (they're in the AppUpdate flag set in flags.go and handled via populateApplicationFromFlags → AppDescriptor.UserOwners/GroupOwners), so the command does accept them. But your underlying point is fair: the old gotcha asserted server-side replace semantics the CLI can't guarantee. Reworded to describe what the CLI actually sends (the full list you provide; no incremental add/remove-owner flags, unlike labels).

Tests pass and gofumpt is clean.

[shayshim]

Bug: --delete-properties example and gotcha use the wrong separator

In version-update's AIDescription:

Example: --delete-properties="env,owner"
Gotcha: "--delete-properties takes a comma-separated list of keys and removes those keys entirely."

Both are wrong. The flag is parsed by utils.ParseSliceFlag, which splits on semicolon, not comma:

// utils.go
func ParseSliceFlag(flagValue string) []string {
    ...
    values := strings.Split(flagValue, ";")  // semicolon
    ...
}

(Note: the function's own doc comment says "comma-separated" — that's also a pre-existing bug in the comment.)

With --delete-properties="env,owner", ParseSliceFlag returns a single key "env,owner" — it never deletes env and owner separately. The correct invocation is:

--delete-properties="env;owner"

Fix needed in update_app_version_cmd.go:

• Example: --delete-properties="env;owner"
• Gotcha: change "comma-separated" → "semicolon-separated"

And separately, the doc comment on ParseSliceFlag in utils.go should be corrected from "comma-separated" to "semicolon-separated".

[ehl-jf]

Fixed in d6e5fba. Confirmed --delete-properties is parsed by ParseSliceFlag, which splits on ;, so "env,owner" was being treated as a single literal key. Updated the example to "env;owner" and the gotcha to "semicolon-separated", and corrected the stale "comma-separated" doc comment on ParseSliceFlag itself while I was there.