JGC-473 - Add AI-agent help text to platform-services commands

cli/cli.go

@@ -20,7 +20,12 @@
 	return components.Namespace{
 		Name:        "worker",
 		Description: "Tools for managing workers",
+		AIDescription: "Manage JFrog Workers: TypeScript-based automations triggered by platform events (upload, download, generic events) or cron schedules. " +
+			"Each worker is defined by a manifest.json plus a worker.ts source file in a local directory. " +
+			"Typical lifecycle: 'jf worker init' to scaffold, 'jf worker test-run' to dry-run locally, 'jf worker deploy' to publish, " +
+			"'jf worker execute' to invoke a GENERIC_EVENT worker, 'jf worker undeploy' to remove. " +
+			"All commands require a JFrog Platform server configured via 'jf c add' or 'jf login' (or the JFROG_WORKER_CLI_DEV_* env vars).",
 		Category:    category,
 		Commands: []components.Command{
 			commands.GetInitCommand(),
 			commands.GetDryRunCommand(),

commands/add_secret_cmd.go

@@ -23,7 +23,29 @@
 	return components.Command{
 		Name:        "add-secret",
 		Description: "Add a secret to a worker",
+		AIDescription: `Add or update an encrypted secret in the local manifest.json. The secret value is encrypted with a user-supplied password and stored under manifest.secrets; the plaintext value never leaves the machine until 'jf worker deploy' (or 'jf worker test-run') unwraps it for transmission over TLS.
+
+When to use:
+- Storing an API token, password, or other sensitive value for a worker.
+- Rotating an existing secret (with --edit).
+
+Prerequisites:
+- A valid manifest.json in the current directory.
+- The same encryption password used by any previously added secret in this manifest (all secrets share one password).
+- The secret value, either entered interactively or supplied via JFROG_WORKER_CLI_DEV_ADD_SECRET_VALUE.
+
+Common patterns:
+  $ jf worker add-secret api-token
+  $ jf worker add-secret api-token --edit
+  $ JFROG_WORKER_CLI_DEV_ADD_SECRET_VALUE=xyz jf worker add-secret api-token   # non-interactive
+
+Gotchas:
+- Without --edit, the command fails if a secret with the same name already exists.
+- The encryption password is prompted interactively; reuse the same one for every secret in a given manifest or decryption will fail at deploy time.
+- This command does NOT call the server; it only writes manifest.json. Run 'jf worker deploy' afterwards to push the secret.
+
+Related: jf worker deploy, jf worker test-run`,
 		Aliases:     []string{"as"},
 		Flags: []components.Flag{
 			components.NewBoolFlag(model.FlagEdit, "Whether to update an existing secret.", components.WithBoolDefaultValue(false)),
 		},

commands/deploy_cmd.go

@@ -43,8 +43,34 @@
 
 func GetDeployCommand() components.Command {
 	return components.Command{
 		Name:             "deploy",
 		Description:      "Deploy a worker",
+		AIDescription: `Create or update a worker on the JFrog Platform from the local manifest.json and worker.ts. The command auto-detects whether the worker already exists and issues a POST (create) or PUT (update) accordingly.
+
+When to use:
+- Publishing a new worker after 'jf worker init' and local testing.
+- Pushing updates to an already-deployed worker.
+- Recording a version (number, description, commit SHA) alongside the deployment.
+
+Prerequisites:
+- A valid manifest.json and worker.ts in the current directory.
+- Configured server (jf c add or jf login) with permission to manage workers in the target scope (project or platform).
+- For SCHEDULED_EVENT workers, manifest.json must include a valid filterCriteria.schedule (see 'jf worker edit-schedule').
+
+Common patterns:
+  $ jf worker deploy
+  $ jf worker deploy --no-secrets
+  $ jf worker deploy --version 1.2.3 --description "Add filter" --commit-sha abc1234
+  $ jf worker deploy --base64
+  $ jf worker deploy --format json
+
+Gotchas:
+- Secrets in manifest.json are decrypted locally and sent in plaintext over TLS unless --no-secrets is set.
+- Filter criteria are only sent when the action requires them (e.g. BEFORE_UPLOAD with a repo filter, SCHEDULED_EVENT with a cron).
+- The --base64 flag is ignored by servers that do not support base64-encoded source code.
+- Versioning fields are only validated against the server's version policy when at least one of --version / --description / --commit-sha is set.
+
+Related: jf worker test-run, jf worker undeploy, jf worker list, jf worker edit-schedule`,
 		Aliases:          []string{"d"},
 		SupportedFormats: []format.OutputFormat{format.Json},
 		Flags: []components.Flag{

commands/dry_run_cmd.go

@@ -29,8 +29,34 @@
 
 func GetDryRunCommand() components.Command {
 	return components.Command{
 		Name:             "test-run",
 		Description:      "Dry run a worker",
+		AIDescription: `Send the local worker source code to the platform's sandbox and execute it against a sample payload without deploying. Use this to iterate on logic before 'jf worker deploy'.
+
+When to use:
+- Validating new or modified worker.ts logic against a realistic payload.
+- Reproducing a failure without touching the deployed worker.
+- Smoke-testing secret handling before promoting changes.
+
+Prerequisites:
+- A valid manifest.json and worker.ts in the current directory (run 'jf worker init' first).
+- Configured server (jf c add or jf login).
+- The action declared in manifest.json must be supported by the target server.
+
+Common patterns:
+  $ jf worker test-run '{"repoPath":"my-repo/path/to/artifact"}'
+  $ jf worker test-run @./sample-payload.json
+  $ jf worker test-run @- < sample-payload.json
+  $ jf worker test-run --no-secrets '{}'
+  $ jf worker test-run --format table '{}'
+
+Gotchas:
+- The payload argument is required and must match what the action delivers at runtime; check types.ts for the expected shape.
+- Use '@filename' to load the payload from a file and '@-' to read it from stdin.
+- By default, secrets in manifest.json are decrypted and sent as staged secrets; pass --no-secrets to omit them.
+- The 'debug' flag in manifest.json controls whether debug logs are returned by the sandbox.
+
+Related: jf worker deploy, jf worker execute, jf worker init`,
 		Aliases:          []string{"dry-run", "dr", "tr"},
 		SupportedFormats: []format.OutputFormat{format.Json, format.Table},
 		DefaultFormat:    format.Json,

commands/edit_schedule_cmd.go

@@ -24,7 +24,30 @@
 	return components.Command{
 		Name:        "edit-schedule",
 		Description: "Edit the schedule criteria of a SCHEDULED_EVENT worker",
+		AIDescription: `Update the cron expression and timezone of a SCHEDULED_EVENT worker's local manifest.json. The change is written to disk only; run 'jf worker deploy' afterwards to apply it on the server.
+
+When to use:
+- Changing the firing cadence of an existing SCHEDULED_EVENT worker.
+- Adjusting the timezone (e.g. switching from UTC to America/New_York).
+- Recovering from a malformed schedule by overwriting filterCriteria.schedule.
+
+Prerequisites:
+- A manifest.json in the current directory whose action is SCHEDULED_EVENT.
+- A valid cron expression with minutes resolution (seconds resolution is not supported by the Worker service).
+- (Optional) An IANA timezone name; defaults to UTC.
+
+Common patterns:
+  $ jf worker edit-schedule --cron "0 * * * *"
+  $ jf worker edit-schedule --cron "*/15 * * * *" --timezone "America/New_York"
+  $ jf worker edit-schedule --cron "0 9 * * 1-5" --timezone "Europe/Paris"
+
+Gotchas:
+- The command refuses to run if manifest.action is not SCHEDULED_EVENT.
+- Cron expressions must have exactly 5 fields (minute hour day month dow); 6-field (with seconds) expressions are rejected.
+- The change is local only — nothing is sent to the server until 'jf worker deploy'.
+
+Related: jf worker deploy, jf worker init, jf worker list-event`,
 		Aliases:     []string{"es"},
 		Flags: []components.Flag{
 			components.NewStringFlag(flagScheduleCron, "A standard cron expression with minutes resolution. Seconds resolution is not supported by Worker service.", components.SetMandatory()),
 			components.NewStringFlag(flagScheduleTimezone, "The timezone to use for scheduling.", components.WithStrDefaultValue("UTC")),

commands/execute_cmd.go

@@ -18,8 +18,33 @@
 
 func GetExecuteCommand() components.Command {
 	return components.Command{
 		Name:             "execute",
 		Description:      "Execute a GENERIC_EVENT worker",
+		AIDescription: `Invoke a deployed GENERIC_EVENT worker on the server with a JSON payload. Unlike 'test-run', this runs the published version of the worker (including its server-side secrets) and is the supported way to trigger a worker on demand.
+
+When to use:
+- Calling a GENERIC_EVENT worker from a script or CI job.
+- Smoke-testing a freshly deployed worker against production state.
+- Reproducing an issue using the exact deployed code.
+
+Prerequisites:
+- The worker must already be deployed (see 'jf worker deploy') and of action type GENERIC_EVENT.
+- Configured server (jf c add or jf login) with execute permission on the worker.
+- If the worker is namespaced under a project, pass --project or run inside a directory whose manifest.json declares it.
+
+Common patterns:
+  $ jf worker execute my-worker '{"hello":"world"}'
+  $ jf worker execute my-worker @./payload.json
+  $ jf worker execute @- < payload.json    # worker name read from manifest.json
+  $ jf worker execute my-worker '{}' --project my-project
+  $ jf worker execute my-worker '{}' --format table
+
+Gotchas:
+- Only GENERIC_EVENT workers can be triggered with this command; event-driven workers (BEFORE_UPLOAD, etc.) fire when the underlying event occurs.
+- If you omit the worker name, the name is read from manifest.json and the last argument is treated as the payload.
+- Use '@file' or '@-' to load the payload from a file or stdin instead of inlining JSON.
+
+Related: jf worker deploy, jf worker test-run, jf worker execution-history`,
 		Aliases:          []string{"exec", "e"},
 		SupportedFormats: []format.OutputFormat{format.Json, format.Table},
 		DefaultFormat:    format.Json,

commands/init_cmd.go

@@ -25,7 +25,29 @@
 	return components.Command{
 		Name:        "init",
 		Description: "Initialize a worker",
+		AIDescription: `Scaffold a new worker project in the current working directory. Generates manifest.json, worker.ts, package.json, tsconfig.json, types.ts, and (unless --no-test) worker.spec.ts based on the action's metadata fetched from the server.
+
+When to use:
+- Starting a new worker locally before editing TypeScript and deploying.
+- Regenerating boilerplate after picking a different action type.
+
+Prerequisites:
+- Configured server (jf c add or jf login) — the server is queried to discover available actions and their TypeScript types.
+- The 'action' must be a valid action name; run 'jf worker list-event' to list them.
+- Run the command from an empty (or expendable) directory; existing files are not overwritten unless --force is set.
+
+Common patterns:
+  $ jf worker init BEFORE_DOWNLOAD my-worker
+  $ jf worker init GENERIC_EVENT my-worker --no-test
+  $ jf worker init SCHEDULED_EVENT nightly-cleanup --project my-project --force
+
+Gotchas:
+- Files are written to the current directory, not a subdirectory named after the worker.
+- Without --force, the command aborts if any target file already exists.
+- The action name is case-sensitive and must match exactly (e.g. BEFORE_UPLOAD, not before_upload).
+
+Related: jf worker list-event, jf worker deploy, jf worker test-run`,
 		Aliases:     []string{"i"},
 		Flags: []components.Flag{
 			plugins_common.GetServerIdFlag(),
 			model.GetProjectKeyFlag(),

commands/list_cmd.go

@@ -22,8 +22,32 @@
 
 func GetListCommand() components.Command {
 	return components.Command{
 		Name:             "list",
 		Description:      "List workers. The default output is a CSV format with columns <name>,<action>,<description>,<enabled>.",
+		AIDescription: `List workers deployed on the JFrog Platform, optionally filtered by action type. Default output is CSV (name, action, description, enabled); JSON output includes full worker details.
+
+When to use:
+- Discovering existing workers before deploying a new one (to avoid name collisions).
+- Auditing which workers are enabled in an environment.
+- Finding the exact worker key to pass to 'jf worker execute' or 'jf worker undeploy'.
+
+Prerequisites:
+- Configured server (jf c add or jf login) with read permission on the worker registry.
+- For project-scoped workers, pass --project (or list global workers without it).
+
+Common patterns:
+  $ jf worker list
+  $ jf worker list BEFORE_UPLOAD
+  $ jf worker list --project my-project
+  $ jf worker list --format json
+  $ jf worker list GENERIC_EVENT --format json
+
+Gotchas:
+- Without --project, only globally scoped workers are returned; project workers are listed separately per project.
+- The deprecated --json flag still works but emits a warning; prefer --format json.
+- The 'action' argument is case-sensitive and must match a name returned by 'jf worker list-event'.
+
+Related: jf worker list-event, jf worker execute, jf worker undeploy`,
 		Aliases:          []string{"ls"},
 		SupportedFormats: []format.OutputFormat{format.Json, format.Table},
 		DefaultFormat:    format.Table,

commands/list_event_cmd.go

@@ -13,8 +13,30 @@
 
 func GetListEventsCommand() components.Command {
 	return components.Command{
 		Name:             "list-event",
 		Description:      "List available events.",
+		AIDescription: `List the action / event types supported by the target server. Use this to discover the valid 'action' values for 'jf worker init' and 'jf worker list'.
+
+When to use:
+- Looking up the exact name of an action (e.g. BEFORE_UPLOAD, GENERIC_EVENT, SCHEDULED_EVENT) before scaffolding a worker.
+- Auditing which applications expose events on a given platform.
+- Inspecting action descriptions and metadata before designing a worker.
+
+Prerequisites:
+- Configured server (jf c add or jf login).
+- For project-scoped action sets, pass --project.
+
+Common patterns:
+  $ jf worker list-event                       # comma-separated names (legacy output)
+  $ jf worker list-event --format table        # NAME,APPLICATION,DESCRIPTION CSV
+  $ jf worker list-event --format json         # full action metadata, including TypeScript types
+  $ jf worker list-event --project my-project --format table
+
+Gotchas:
+- Without --format, the output is a plain comma-separated list (kept for backwards compatibility); pass --format table or --format json for structured output.
+- The set of actions depends on the server's installed applications and on the --project scope.
+
+Related: jf worker init, jf worker list`,
 		Aliases:          []string{"le"},
 		SupportedFormats: []format.OutputFormat{format.Json, format.Table},
 		DefaultFormat:    format.None,

commands/remove_cmd.go

@@ -17,8 +17,30 @@
 
 func GetRemoveCommand() components.Command {
 	return components.Command{
 		Name:             "undeploy",
 		Description:      "Undeploy a worker",
+		AIDescription: `Delete a deployed worker from the JFrog Platform. The worker stops handling events immediately; its source, secrets, and schedule are removed server-side. Local files (manifest.json, worker.ts) are not touched.
+
+When to use:
+- Decommissioning a worker that is no longer needed.
+- Cleaning up test workers from a non-production environment.
+- Removing a misconfigured worker before redeploying.
+
+Prerequisites:
+- Configured server (jf c add or jf login) with delete permission on the worker.
+- If the worker is namespaced under a project, run from a directory whose manifest.json declares the project, or pass the worker key directly.
+
+Common patterns:
+  $ jf worker undeploy my-worker
+  $ jf worker undeploy           # worker name taken from manifest.json
+  $ jf worker undeploy my-worker --format json
+
+Gotchas:
+- This operation is irreversible from the server; redeploy with 'jf worker deploy' to restore.
+- Execution history is retained server-side and remains visible via 'jf worker execution-history' for a configured retention period.
+- The command exits cleanly even if the worker did not exist when run with --format json (the response body is empty/204).
+
+Related: jf worker deploy, jf worker list`,
 		Aliases:          []string{"rm"},
 		SupportedFormats: []format.OutputFormat{format.Json},
 		Flags: []components.Flag{

commands/show_execution_history_cmd.go

@@ -30,6 +30,30 @@ func GetShowExecutionHistoryCommand() components.Command {
 	return components.Command{
 		Name:             "execution-history",
 		Description:      "Show a worker execution history.",
+		AIDescription: `Fetch the recent execution history of a deployed worker. Each entry includes start/end times, status, who triggered it, the executed version, and a trace ID for cross-referencing platform logs.
+
+When to use:
+- Investigating why a scheduled or event-driven worker failed.
+- Confirming that a newly deployed worker is running on the expected schedule.
+- Correlating worker activity with platform audit logs via trace ID.
+
+Prerequisites:
+- The worker must already be deployed.
+- Configured server (jf c add or jf login) with read access to execution history.
+- For project-scoped workers, pass --project or run from a manifest directory that declares it.
+
+Common patterns:
+  $ jf worker execution-history my-worker
+  $ jf worker execution-history               # worker name read from manifest.json
+  $ jf worker execution-history my-worker --with-test-runs
+  $ jf worker execution-history my-worker --project my-project --format table
+
+Gotchas:
+- Test runs (from 'jf worker test-run') are excluded by default; pass --with-test-runs to include them.
+- Default output is JSON; pass --format table for a CSV view with human-readable timestamps in UTC.
+- History retention is controlled by the server and may be limited.
+
+Related: jf worker execute, jf worker deploy, jf worker test-run`,
 		Aliases:          []string{"exec-hist", "eh"},
 		SupportedFormats: []format.OutputFormat{format.Json, format.Table},
 		DefaultFormat:    format.Json,