world-manager/docs/provider-refactor-migration-plan.md

Provider Refactor Migration Plan

This plan moves the app from a Bedrock-oriented source-access architecture to an engine/platform-provider architecture while keeping behavior working at each step.

Phase 1: Document and Name the Boundary

• Add provider architecture documentation.
• Add neutral model names alongside existing names:
  • MinecraftEdition
  • MinecraftContentKind
  • MinecraftPlatformContentType
  • PlatformContentMetadata
  • ContentItemCapabilities
  • SourceAccessStatus
  • WorkStage
  • ProviderEvent
• Keep existing MinecraftContentType as a compatibility alias/wrapper until call sites move.

Phase 2: Neutralize Content Items

• Add edition, kind, platform type, capabilities, and platform metadata to MinecraftContentItem.
• Preserve existing Bedrock fields as computed compatibility accessors where practical.
• Move Bedrock world and pack metadata into BedrockContentMetadata.
• Update search text to pull from generic fields and provider metadata.
• Update tests/fixtures to construct items through the new neutral initializer.

Phase 3: Provider-Shaped Access

• Introduce provider protocol types as a superset of current source access.
• Adapt SourceAccessMethod to emit provider IDs and access status.
• Register providers through a provider registry/coordinator.
• Rename current generic local folder access to Bedrock local folder access.
• Keep a compatibility typealias or wrapper named LocalFolderSourceAccess until all call sites are migrated.

Phase 4: Split Bedrock Platform Module

• Move Bedrock-specific scanner/metadata/export code under a Bedrock platform namespace/folder.
• Rename WorldScanner to BedrockContentScanner.
• Rename MinecraftContentMetadataReader to BedrockContentMetadataReader.
• Keep temporary wrappers for Quick Look and legacy call sites.
• Move Bedrock relationship building out of generic indexing.

Phase 5: Event-Driven Scan Pipeline

• Add provider events and work stages.
• Let providers report progress stages.
• Let the engine consume discovered/inspected events.
• Preserve existing scan-stage behavior until provider events fully replace it.
• Keep worker limits in the engine, with provider-declared concurrency policy as a later extension.

Phase 6: Capability-Aware Actions

• Move archive extension and portable export format selection off MinecraftContentType.
• Add item/provider capabilities for reveal/export/share/copy.
• Adapt ContentItemActionService and exporters to route by provider/platform type.
• Keep Bedrock package output unchanged.

Phase 7: Java Local Provider

• Add Java local provider as read-only initially.
• Discover Java saves, resource packs, and datapacks.
• Add Java metadata reader for level.dat and pack.mcmeta incrementally.
• Export Java folder-backed content as .zip where supported.
• Do not add Java-Bedrock conversion in this phase.

Phase 8: Cleanup

• Remove compatibility aliases after UI, tests, Quick Look, and exporters use provider-aware models.
• Rename UI labels from Bedrock-specific categories where appropriate.
• Add provider fixtures and contract tests.
• Keep build/test verification passing after each phase.

Verification

At each milestone:

• Run Swift tests.
• Run the app target build.
• Check existing Bedrock local and connected-device behavior remains intact.
• Add focused tests for model migration, indexing, export format selection, and provider event consumption.