feat(sync): add --force-upload flag to control S3 upload dedup

[vishwakt]

Which issue(s) does this change fix?

Closes #8168

Why is this change necessary?

sam sync currently hardcodes force_upload=True in three places. That bypasses the SHA-based dedup inside S3Uploader.upload_with_dedup, so every sync re-zips and re-uploads every artifact to S3 even when nothing has actually changed. The original issue reports a 20%+ (~90s) speedup per run from disabling this on a fork.

How does it address the issue?

Exposes --force-upload on sam sync, defaulting to False (matching the default on sam deploy and sam package), and threads the flag through every code path that was previously hardcoded:

1. samcli/commands/sync/command.py — replaces force_upload=True in PackageContext(...) and DeployContext(...) with the new option.
2. samcli/lib/sync/flows/zip_function_sync_flow.py — the S3Uploader constructed for oversized lambda zips now reads force_upload from self._deploy_context.force_upload instead of hardcoding True. This was the third code path that defeated the dedup.
3. Reuses the existing force_upload_option() decorator from samcli/commands/_utils/options.py, so help text, click metadata, and config-file plumbing are consistent with sam deploy / sam package.
4. schema/samcli.json was regenerated via python -m schema.make_schema and now lists force_upload as a sync parameter.

Users who actually want the old behavior can pass --force-upload.

What side effects does this change have?

• Default behavior change. Without --force-upload, sam sync will now skip uploading artifacts whose SHA already exists in S3 — which is what the issue requester (and the maintainer who welcomed a PR) asked for. Backward-compatible toggle via the new flag.
• No change to non-sync commands.
• No new dependencies or schema breaking changes; the schema gained one optional boolean property.

Tests

• tests/unit/commands/sync/test_command.py — existing assertions updated from force_upload=True to force_upload=self.force_upload, plus a new parameterized test (test_force_upload_flag_propagates_to_package_and_deploy_contexts) covering both True and False and asserting the value reaches both PackageContext and DeployContext.
• tests/unit/lib/sync/flows/test_zip_function_sync_flow.py — new parameterized test (test_s3_uploader_uses_deploy_context_force_upload) confirming the S3Uploader is constructed with deploy_context.force_upload for both values.
• tests/unit/commands/samconfig/test_samconfig.py — do_cli arg-order assertion updated for the new positional parameter.
• Full unit suite passes locally: 9131 passed, 25 skipped.
• black --check setup.py samcli tests schema and ruff check samcli schema are both clean locally.

Mandatory Checklist

• Review the generative AI contribution guidelines
• Add input/output type hints to new functions/methods
• Write design document if needed (not needed — surface-level flag mirroring an existing pattern in sam deploy / sam package)
• Write/update unit tests
• Write/update integration tests (happy to add if maintainers want — would live under tests/integration/sync/)
• Write/update functional tests if needed
• make pr passes locally (black --check, ruff check, python -m schema.make_schema, full unit suite)
• make update-reproducible-reqs if dependencies were changed (no dep changes)
• Write documentation (help text on the flag is auto-generated by force_upload_option; no separate docs file in this repo for this command)

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[aws-sam-tooling-bot]

Code Review Results

Reviewed: d8dc699..b4084c3
Files: 6
Comments: 1

[aws-sam-tooling-bot]

[BUG] The new option will not appear in sam sync --help because it was never registered in samcli/commands/sync/core/options.py.

SyncCommand.format_options delegates to CoreCommand._format_options(..., formatting_options=OPTIONS_INFO), and that helper only renders parameters whose name is present in one of the groups:

for param in params
if param.name in options.get("option_names", {}).keys()

Since force_upload is absent from REQUIRED_OPTIONS, AWS_CREDENTIAL_OPTION_NAMES, INFRASTRUCTURE_OPTION_NAMES, CONFIGURATION_OPTION_NAMES, ADDITIONAL_OPTIONS, and OTHER_OPTIONS, the flag is silently dropped from the help output. It is also missing from ALL_OPTIONS, which the formatter uses for column justification.

This is the reason sam deploy and sam package register it explicitly — samcli/commands/deploy/core/options.py:39 and samcli/commands/package/core/options.py both list "force_upload" under their DEPLOYMENT_OPTIONS group. No existing unit test catches this: tests/unit/commands/sync/core/test_command.py stubs get_params with a fixed list, so the help assertions pass either way.

Because the PR flips the effective default for sam sync, an undiscoverable opt-out flag is a concrete usability problem: users who hit a regression have no way to find --force-upload from the CLI. Sync has no DEPLOYMENT_OPTIONS group, so the closest match to the decorator placement is the infrastructure group:

INFRASTRUCTURE_OPTION_NAMES: List[str] = [
   "parameter_overrides",
   "capabilities",
   "s3_bucket",
   "force_upload",
   "s3_prefix",
   ...
]

Consider also adding a tests/unit/commands/sync/core/test_options.py mirroring the existing test_all_options_formatted test that other commands have (deploy, package, build, logs, etc.), which asserts sorted(ALL_OPTIONS) == sorted(command_options + ["help"]). That test is what would have caught this, and sync is currently one of the few commands missing it.