feat(eng-12002): Add metadata flag to push command

[BartoszBlizniak]

Description

Adds push-time metadata flags to cloudsmith push <format> so SBOM / BuildInfo / generic JSON can be attached in a single command instead of a separate cloudsmith metadata add follow-up.

New flags on every push subcommand:

• --metadata-content-file PATH (or - for stdin)
• --metadata-content JSON
• --metadata-content-type MIME
• --metadata-source-identity TEXT
• --on-metadata-failure [error|warn]

Flow:

1. Resolve + JSON-object validation locally (stdin is consumed once, payload validated once per push). Combining metadata flags with multiple package files is rejected with a UsageError — a single metadata payload semantically belongs to one package, so silently fanning it out across N packages (and validating + attaching it N times) is almost never the intent. Push files individually when attaching metadata.
2. Pre-validate payload via POST /v2/metadata/validate/ before any S3 upload — malformed metadata can no longer leave orphan packages.
3. After create_package, attach metadata via POST /v2/metadata/.
4. Failures are fatal by default (CI surfaces broken SBOMs). Opt out via --on-metadata-failure warn flag, CLOUDSMITH_METADATA_FAILURE_MODE=warn (or 0) env var, or metadata_failure_mode = warn in config.ini. Precedence: flag > env > config > default (error). Downgrades to a warning + copy-paste retry hint.
5. Result is surfaced under metadata_attachment in JSON output (success and error envelopes).

Reuses shared metadata helpers from cli/metadata_common.py

Stacked on top of #292 (refactor/metadata-common). Base will retarget to master once #292 merges.

Type of Change

• New feature
• Refactoring
• Bug fix
• Breaking change
• Documentation update
• Other

Additional Notes

• Default mode aborts the push on validation/attach failure with the HTTP status as the exit code.
• Three opt-out paths for downgrading failures to a warning (package still uploads): --on-metadata-failure warn flag (per push), CLOUDSMITH_METADATA_FAILURE_MODE=warn env var (per shell / CI step), metadata_failure_mode = warn in config.ini (persistent). Precedence: flag > env > config > default. Invalid config-file values raise a UsageError at load time instead of silently falling back to error.
• Multi-file push (cloudsmith push <format> ... file1 file2 ...) combined with any metadata flag is rejected up-front with a UsageError. Push files individually when attaching metadata, or drop the flags for a bulk upload.

Examples

Push:

cloudsmith push raw ${ORG}/${REPO} payload.txt --name metadata-demo --version 1.0.0 --republish --metadata-content '{"build_id": "demo-inline", "git_sha": "abc123"}' --metadata-content-type application/json

Checking raw package upload parameters ... OK
Validating metadata content from inline ... OK
Checking payload.txt file upload parameters ... OK
Requesting file upload for payload.txt ... OK
Uploading payload.txt:  [####################################]  100%
Creating a new raw package ... OK
Created: bart-demo-org/821/payloadtxt-wu4u (bONvPYh5LfhH)
Attaching metadata to package bONvPYh5LfhH ... OK
Metadata attached: bart-demo-org/821/payloadtxt-wu4u/ATkdRL03Uwk6

Synchronising payloadtxt-wu4u:  [####################################]  100%  Completed / Fully Synchronised

Package synchronised successfully in 16.006934 second(s)!

Push with invalid metadata (default, hard fail):

cloudsmith push raw ${ORG}/${REPO} payload.txt --name metadata-demo --version 1.0.0 --republish --metadata-content-file buildinfo-broken.json --metadata-content-type application/vnd.jfrog.buildinfo+json

Checking raw package upload parameters ... OK
Validating metadata content from buildinfo-broken.json ... FAILED
ERROR
Metadata content failed validation (HTTP 422): Invalid input. (status: 422 - Unprocessable Entity)

Detail: Invalid input.
Content Field: Content does not conform to the schema for content type 'application/vnd.jfrog.buildinfo+json'.

Push with invalid metadata, downgraded via the --on-metadata-failure warn flag:

cloudsmith push raw ${ORG}/${REPO} payload.txt --name metadata-demo --version 1.0.0 --republish --metadata-content-file buildinfo-broken.json --metadata-content-type application/vnd.jfrog.buildinfo+json --on-metadata-failure warn

Checking raw package upload parameters ... OK
Validating metadata content from buildinfo-broken.json ... FAILED
Metadata content failed validation (HTTP 422): Invalid input.
Package upload will continue without metadata. Pass ``--on-metadata-failure error`` (or set the ``metadata_failure_mode`` config key / ``$CLOUDSMITH_METADATA_FAILURE_MODE`` env var to ``error``) to fail the push instead.
Checking payload.txt file upload parameters ... OK
Requesting file upload for payload.txt ... OK
Uploading payload.txt:  [####################################]  100%
Creating a new raw package ... OK
Created: bart-demo-org/821/payloadtxt-6mm2 (H4Q1EDW8Gm2E)

Fix the metadata content, then run:
cloudsmith metadata add bart-demo-org/821/payloadtxt-6mm2 --file buildinfo-broken.json --content-type application/vnd.jfrog.buildinfo+json

Synchronising payloadtxt-6mm2:  [####################################]  100%  Completed / Fully Synchronised

Package synchronised successfully in 6.121764 second(s)!

Same downgrade via the env var (backward-compatible path for CI wrappers):

CLOUDSMITH_METADATA_FAILURE_MODE=warn cloudsmith push raw ${ORG}/${REPO} payload.txt --name metadata-demo --version 1.0.0 --republish --metadata-content-file buildinfo-broken.json --metadata-content-type application/vnd.jfrog.buildinfo+json

Or persistently via ~/.config/cloudsmith/config.ini:

[default]
metadata_failure_mode = warn

Resolution order when more than one is set: --on-metadata-failure flag > $CLOUDSMITH_METADATA_FAILURE_MODE env var > metadata_failure_mode config key > default (error).

[jmatchetttestuser]

@claude review

(Sent as an external user with no permissions)

[Copilot]

Pull request overview

Adds push-time metadata support so package uploads can validate and attach metadata during cloudsmith push.

Changes:

• Adds metadata resolution, validation, attachment, retry hints, and failure-mode handling to push commands.
• Surfaces metadata attachment status in JSON success/error output.
• Adds extensive unit coverage for metadata validation, attachment, warnings, retry hints, and JSON envelopes.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
cloudsmith_cli/cli/commands/push.py	Implements push-time metadata options and attachment flow.
cloudsmith_cli/cli/exceptions.py	Adds metadata context to JSON API error envelopes.
cloudsmith_cli/cli/tests/test_push.py	Adds tests for push metadata behaviors and helper output.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.