feat(cli): add prune command for orphaned state-file cleanup

[michael-richey]

Summary

Third and final stacked PR — adds the user-visible datadog-sync prune command that deletes orphaned per-resource state files when source resources are removed upstream.

Stacked on: #554 (PR 2 — state helpers) → which is stacked on #553 (PR 1 — storage primitives).

Why

--resource-per-file mode (mandatory for batched managed-sync workflows) writes per-resource JSON files that are never removed when the underlying resource is deleted upstream. Over time thousands of orphaned files accumulate, slowing list operations and polluting future loads.

prune is the explicit cleanup pass.

How it works

1. Fetches authoritative source IDs via import_resources_without_saving (read-only against source — no destination calls).
2. Builds the expected-filename set from the in-memory source IDs (sanitization + collision skip).
3. Lists actual filenames on disk under source/ and destination/.
4. Computes the set difference — files on disk minus expected.
5. Snapshot fence: re-lists once more and intersects, guarding against a concurrent sync writing a file between the import and the prune.
6. Prompts for confirmation (skipped with --force; dry-runs with --dry-run; refuses interactive prompts under --json without --force or --dry-run).
7. Deletes via storage.delete_many; emits per-(origin, type) NDJSON ResourceOutcome events with status="success" or "partial".

Refusals (UsageError before any API call)

• --resources must be explicit — defaulting to all types is too dangerous for a destructive command.
• --filters rejected — would over-prune filtered-out resources.
• --resource-per-file required — no per-file stale problem in monolithic mode.
• --json requires --force or --dry-run — no interactive prompts in JSON mode.

Wiring

• Command.PRUNE in constants.py.
• commands/prune.py with @source_auth_options, @common_options, @storage_options + --force, --dry-run.
• New dispatch branch in run_cmd_async.
• Configuration gains resource_per_file, prune_force, prune_dry_run fields; build_config wires them post-construction.
• _handle_deprecated is gated off for PRUNE so legacy-file presence doesn't silently mutate resources_arg.
• init_async adds PRUNE to source-only _validate_client and _verify_ddr_status lists; PRUNE is excluded from destination validation, destination DDR checks, and send_metrics start events.

Test plan

• 13 new unit tests in `tests/unit/test_prune_cli.py`: CLI argparse smoke (`--help`, `--resources` required, flags accepted), handler preconditions (`--resource-per-file`, `--filters`, `--json` matrix), flow tests (dry-run skip-delete, force skip-confirm, partial-failure emit, empty-stale logging, snapshot-fence intersection).
• Full unit suite: 472/472 passing.
• `tox -e ruff,black` clean.

Out-of-scope (deferred)

• Integration test with VCR cassette — requires recording against a real org. The plan calls for one in `tests/integration/test_cli/test_prune.py`; happy to add as a follow-up if requested.
• Batch-delete optimization for S3 (`DeleteObjects` API). The `delete_many` abstraction is in place so a future PR can override it for S3 without touching callers.
• Cross-process concurrency lock. The snapshot fence covers the common case (sync running concurrently between import and prune). Sync writing during the prune itself, or in-process import racing with prune, are out of scope.

Stacked PR context

• ✅ PR 1 — Storage primitives (feat(storage): add list_filenames, delete, delete_many primitives #553)
• ✅ PR 2 — State helpers (feat(state): add compute_stale_files and delete_stale_files helpers #554)
• 👉 PR 3 — `prune` command (this PR)

🤖 Generated with Claude Code

The base branch was changed.