Extract does not remove stale artifacts, causing Publish delete-unmatched to republish deleted APIM resources

[mebecker]

Summary

Running extract multiple times into the same artifact directory leaves files for resources that were deleted from the source APIM. Later, publish with delete-unmatched treats those stale files as desired state and can recreate resources in target APIM that should remain deleted.

Problem Statement
Extract currently writes and updates files but does not clean artifacts that no longer exist in source APIM.
Delete-unmatched compares target APIM to what exists on disk, so stale files in artifactDir are interpreted as intentional and prevent intended deletion behavior.

Repro Steps

1. Run extract to artifactDir from source APIM containing resource A and B.
2. Delete resource A from source APIM.
3. Run extract again to the same artifactDir.
4. Observe resource A files still present in artifactDir.
5. Run publish to target APIM with delete-unmatched.
6. Resource A is not treated as removed and may be recreated or retained unexpectedly.

Expected Behavior
After extract, artifactDir reflects current source APIM exactly for the selected scope.
Resources removed from source APIM should no longer exist in artifactDir, so publish delete-unmatched can remove them from target APIM.

Actual Behavior
Extract leaves stale files in artifactDir. Publish delete-unmatched uses stale files as source-of-truth and does not produce correct cleanup behavior.

Impact

1. Drift between source and target APIM is preserved or reintroduced.
2. Deleted resources can reappear in downstream environments.
3. Users must manually clear artifactDir before extract, which is error-prone.

Proposed Fix
Add extraction cleanup behavior before writing artifacts:

• Option A: Always clean managed artifact paths at start of extract.
• Option B: Add a clean flag and enable it in generated CI workflows by default. (Semantics TBD - perhaps name the flag --delete-unmatched for symmetry with publish command.)
• Ensure cleanup is scope-aware for filtered extraction to avoid accidental deletion of intentionally unmanaged files.