file-provider-and-finder-sync-workflow

File Provider and Finder Sync Workflow

Purpose

Choose the correct filesystem extension model. File Provider is the modern path for remote-storage synchronization: it enumerates items, materializes content, receives file operations, and reports remote changes to the system. Finder Sync is a macOS Finder UI extension for monitored-folder badges, contextual menus, and visibility; it does not implement remote synchronization itself.

This skill owns that decision, File Provider synchronization mechanics, and Finder Sync’s limited UI role. It does not own a storage backend protocol, generic networking, or unrelated app-extension architecture.

When To Use

• Use this skill when an Apple app exposes remote storage in Files or Finder, synchronizes cloud-backed files, handles placeholders, materializes content, or reconciles remote changes.
• Use this skill when a macOS app needs Finder badges, toolbar/contextual menus, selected-item context, or monitored-folder visibility.
• Use app-extension-architecture-workflow when target/process, entitlement, app-group, or general extension decisions remain unresolved.
• Use swift-openapi-client-workflow or server-side skills when the storage service contract or transport is the main unresolved concern.
• Use xcode-build-run-workflow, xcode-testing-workflow, and macos-distribution-workflow for execution, testing, and release evidence.

Single-Path Workflow

1. Classify the requested outcome:
   • choose File Provider when users need remote files to appear, hydrate, upload, rename, move, delete, remain available offline as supported, and reconcile with a remote service
   • choose Finder Sync only when the files already exist locally and the product needs Finder badges, menus, or monitored-folder UI
   • combine them only when File Provider owns sync and Finder Sync has a separately justified, narrow Finder UI role
2. State the documented behavior relied on:
   • a File Provider extension enumerates storage and implements file operations; the system asks it to materialize content and notify the system of remote changes
   • the File Provider working set drives background updates, materialized availability, and Spotlight visibility
   • Finder Sync manages directoryURLs, badges, selected items, and menu/visibility UI for monitored folders; it is not a sync implementation
3. Design File Provider as the synchronization authority:
   • define stable item identifiers, parent hierarchy, version/anchor handling, placeholders, materialization, upload, rename/move/delete, conflict behavior, and cancellation
   • distinguish local intent from confirmed remote state and maintain a durable retry/reconciliation plan
   • signal remote changes with the documented File Provider notification/enumerator path or supported push path; do not pollute Finder UI callbacks with sync work
   • keep backend transport behind a small, typed client boundary and avoid treating local file paths as durable remote IDs
4. Bound Finder Sync:
   • monitor only the necessary local directories
   • use badges and menus to represent known local state, explain uncertainty, and initiate explicit app actions when needed
   • do not claim Finder Sync observes all disk changes, transfers files, owns conflict resolution, or makes remote content available
5. Protect people’s files:
   • minimize metadata and content access, avoid logging file names or paths unnecessarily, and describe sync/error state honestly
   • keep user actions, destructive remote changes, conflict choices, and offline behavior visible and recoverable
6. Validate:
   • File Provider: domain/account lifecycle, enumeration, placeholders, fetch, upload, rename/move/delete, working-set changes, remote notifications, offline behavior, cancellation, conflicts, and upgrade/recovery
   • Finder Sync: extension enablement, monitored directories, badge update, menu context, selected-item behavior, disabled state, and Finder restart/relaunch behavior
   • validate target entitlements, signing, embedding, and distribution separately from service integration tests
7. Return the chosen model, documented behavior, ownership map, backend handoff, privacy policy, validation matrix, and next workflow.