fix(eng-13978): JSON output for package sync failure with status reason

[BartoszBlizniak]

Description

cloudsmith push <format> crashed with UnboundLocalError: cannot access local variable 'reason' instead of reporting why a sync failed. Only in -F json/pretty_json mode, whose polling loop discarded the status fields from get_package_status. Now it keeps them, so failures print the stage and the server's reason like the progressbar path already did.

JSON mode also left nothing on stdout when a sync failed, since the human-readable text goes to stderr. Failures now emit an error envelope on stdout, matching the shape handle_api_exceptions produces for API failures.

Also rewrites AGENTS.md: the tooling sections still documented black/isort/flake8/pylint after the move to ruff.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Refactoring
• Other (please describe)

Additional Notes

Before - pushing a duplicate package with -F json:

  File ".../cloudsmith_cli/cli/commands/push.py", line 757, in wait_for_package_sync
    if reason:
       ^^^^^^
UnboundLocalError: cannot access local variable 'reason' where it is not associated with a value

After - parseable envelope on stdout, human-readable text on stderr, exit code 1:

{"detail": "A package with ... name 'your-package' ... already exists in the 'your-namespace/your-repo: your-package@1.0.0' package. \"Replace Package w/ Same Version\" was not enabled for your package. - This package should be deleted.", "help": {"context": "Failed to synchronise file!", "hint": null}, "meta": {"status": "Failed", "stage": "Parsing Package Metadata", "seconds": 7.281036}}

meta carries status/stage/seconds rather than code/description, since a sync failure has no HTTP status.

Not breaking: pretty output untouched, success path still emits {"data": {...}}, and failures already exited 1 for anyone who did not hit the crash.

To verify beyond CI, push the same package twice to a repo without "Replace Package w/ Same Version" enabled, with -F json --sync-attempts 1. Tested locally against a scratch repo on a personal fork.

[Copilot]

Pull request overview

Fixes a crash and improves machine-readable error reporting for cloudsmith push <format> when a package sync fails under -F json / pretty_json, ensuring the server-provided failure reason is preserved and emitted.

Changes:

• Preserve status/stage/reason from get_package_status() in the JSON-mode polling path to avoid UnboundLocalError and to surface the sync failure reason.
• Emit a JSON error envelope to stdout on sync failure in JSON output modes (while keeping human-readable failure text on stderr).
• Add a regression test covering JSON-mode sync failure output (stderr text + stdout envelope).

Reviewed changes

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

File	Description
cloudsmith_cli/cli/commands/push.py	Fixes JSON-mode sync polling to keep failure fields and emits a JSON error envelope on sync failure.
cloudsmith_cli/cli/tests/test_push.py	Adds a regression test ensuring JSON-mode sync failures include the server reason and a parseable stdout envelope.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.