Wire loader to support ModuleRegistry alongside ExtensionSpecification

Phase 3a: Add dual-path instance creation to the AppLoader.

- Add ModuleRegistry field to AppLoader
- Update createExtensionInstance to check registry first via
  descriptor.createModule(), falling back to legacy spec path
- Add createModuleFromDescriptor method for the new path
- Widen findEntryPath signature to accept both specs and descriptors
- Add moduleRegistry to ConfigurationLoaderResult type

The registry is currently empty so all instances still use the legacy
SpecificationBackedExtension path. Next PR will migrate actual specs.

Author: isaacroldan

packages/app/src/cli/models/app/loader.ts

@@ -21,6 +21,8 @@ import {
 import {configurationFileNames, dotEnvFileNames} from '../../constants.js'
 import metadata from '../../metadata.js'
 import {ExtensionInstance, SpecificationBackedExtension} from '../extensions/extension-instance.js'
+import {ModuleRegistry} from '../extensions/module-registry.js'
+import {loadModuleRegistry} from '../extensions/load-specifications.js'
 import {ExtensionsArraySchema, UnifiedSchema} from '../extensions/schemas.js'
 import {ExtensionSpecification, isAppConfigSpecification} from '../extensions/specification.js'
 import {CreateAppOptions, Flag} from '../../utilities/developer-platform-client.js'
@@ -320,6 +322,23 @@ export async function loadAppFromContext<TModuleSpec extends ExtensionSpecificat
     usesCliManagedUrls: configuration.build?.automatically_update_urls_on_dev,
   }
 
+  // Build the module registry and merge remote spec values into it so
+  // descriptors have up-to-date identity data from the platform API.
+  const moduleRegistry = loadModuleRegistry()
+  const remoteSpecsForMerge = specifications.map((spec) => ({
+    name: spec.externalName,
+    externalName: spec.externalName,
+    identifier: spec.identifier,
+    gated: false,
+    externalIdentifier: spec.externalIdentifier,
+    experience: spec.experience as 'extension' | 'configuration' | 'deprecated',
+    managementExperience: 'cli' as const,
+    registrationLimit: spec.registrationLimit,
+    uidStrategy: spec.uidStrategy,
+    surface: spec.surface,
+  }))
+  moduleRegistry.mergeRemoteSpecs(remoteSpecsForMerge)
+
   const loadedConfiguration: ConfigurationLoaderResult<CurrentAppConfiguration, TModuleSpec> = {
     directory: project.directory,
     configPath: configurationPath,
@@ -328,6 +347,7 @@ export async function loadAppFromContext<TModuleSpec extends ExtensionSpecificat
     configSchema,
     specifications,
     remoteFlags,
+    moduleRegistry,
   }
 
   const loader = new AppLoader<CurrentAppConfiguration, TModuleSpec>({
@@ -459,6 +479,7 @@ class AppLoader<TConfig extends CurrentAppConfiguration, TModuleSpec extends Ext
   private readonly loadedConfiguration: ConfigurationLoaderResult<TConfig, TModuleSpec>
   private readonly reloadState: ReloadState | undefined
   private readonly project: Project
+  private readonly moduleRegistry: ModuleRegistry
 
   constructor({
     ignoreUnknownExtensions,
@@ -472,6 +493,7 @@ class AppLoader<TConfig extends CurrentAppConfiguration, TModuleSpec extends Ext
     this.loadedConfiguration = loadedConfiguration
     this.reloadState = reloadState
     this.project = project
+    this.moduleRegistry = loadedConfiguration.moduleRegistry ?? new ModuleRegistry()
   }
 
   private get activeConfigFile(): TomlFile | undefined {
@@ -587,6 +609,14 @@ class AppLoader<TConfig extends CurrentAppConfiguration, TModuleSpec extends Ext
     configurationPath: string,
     directory: string,
   ): Promise<ExtensionInstance | undefined> {
+    // Check the module registry first (new subclass-based path).
+    // If a descriptor is found, use its factory to create the right subclass.
+    const descriptor = this.moduleRegistry.findForType(type)
+    if (descriptor) {
+      return this.createModuleFromDescriptor(descriptor, configurationObject, configurationPath, directory)
+    }
+
+    // Fall back to legacy ExtensionSpecification path.
     const specification = this.findSpecificationForType(type)
     let entryPath
     let usedKnownSpecification = false
@@ -642,6 +672,62 @@ class AppLoader<TConfig extends CurrentAppConfiguration, TModuleSpec extends Ext
     return extensionInstance
   }
 
+  private async createModuleFromDescriptor(
+    descriptor: ReturnType<ModuleRegistry['findForType']> & {},
+    configurationObject: object,
+    configurationPath: string,
+    directory: string,
+  ): Promise<ExtensionInstance | undefined> {
+    const parseResult = descriptor.parseConfigurationObject(configurationObject)
+    if (parseResult.state === 'error') {
+      if (parseResult.errors) {
+        for (const error of parseResult.errors) {
+          this.errors.addError({
+            file: configurationPath,
+            message: error.message ?? `Validation error at ${error.path.join('.')}`,
+          })
+        }
+      }
+      return undefined
+    }
+
+    const configuration = parseResult.data
+    const entryPath = await this.findEntryPath(directory, descriptor)
+
+    const moduleInstance = descriptor.createModule({
+      configuration,
+      configurationPath,
+      entryPath,
+      directory,
+      remoteSpec: {
+        name: descriptor.externalName,
+        externalName: descriptor.externalName,
+        identifier: descriptor.identifier,
+        gated: false,
+        externalIdentifier: descriptor.externalIdentifier,
+        experience: descriptor.experience,
+        managementExperience: 'cli',
+        registrationLimit: descriptor.registrationLimit,
+        uidStrategy: descriptor.uidStrategy,
+        surface: descriptor.surface,
+      },
+    })
+
+    if (this.reloadState && configuration.handle) {
+      const previousDevUUID = this.reloadState.extensionDevUUIDs.get(configuration.handle)
+      if (previousDevUUID) {
+        moduleInstance.devUUID = previousDevUUID
+      }
+    }
+
+    const validateResult = await moduleInstance.validate()
+    if (validateResult.isErr()) {
+      this.errors.addError({file: configurationPath, message: stringifyMessage(validateResult.error).trim()})
+    }
+
+    return moduleInstance
+  }
+
   private async loadExtensions(appDirectory: string, appConfiguration: TConfig): Promise<ExtensionInstance[]> {
     if (this.specifications.length === 0) return []
 
@@ -820,9 +906,10 @@ class AppLoader<TConfig extends CurrentAppConfiguration, TModuleSpec extends Ext
     return configContent ? extensionInstance : undefined
   }
 
-  private async findEntryPath(directory: string, specification: ExtensionSpecification) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private async findEntryPath(directory: string, specification: {identifier: string; appModuleFeatures?: (...args: any[]) => string[]}) {
     let entryPath
-    if (specification.appModuleFeatures().includes('single_js_entry_path')) {
+    if (specification.appModuleFeatures?.().includes('single_js_entry_path')) {
       entryPath = (
         await Promise.all(
           ['index']
@@ -890,6 +977,7 @@ type ConfigurationLoaderResult<
   TModuleSpec extends ExtensionSpecification,
 > = AppConfigurationInterface<TConfig, TModuleSpec> & {
   configurationLoadResultMetadata: ConfigurationLoadResultMetadata
+  moduleRegistry?: ModuleRegistry
 }
 
 /**

packages/app/src/cli/models/extensions/load-specifications.ts

@@ -1,4 +1,5 @@
 import {ExtensionSpecification} from './specification.js'
+import {ModuleRegistry} from './module-registry.js'
 import appHomeSpec, {AppHomeSpecIdentifier} from './specifications/app_config_app_home.js'
 import appProxySpec, {AppProxySpecIdentifier} from './specifications/app_config_app_proxy.js'
 import appPOSSpec, {PosSpecIdentifier} from './specifications/app_config_point_of_sale.js'
@@ -51,6 +52,17 @@ export async function loadLocalExtensionsSpecifications(): Promise<ExtensionSpec
   return loadSpecifications().sort(sortConfigModules)
 }
 
+/**
+ * Load the module registry with all migrated module descriptors.
+ * Descriptors registered here use the new ApplicationModule subclass path
+ * instead of the legacy ExtensionSpecification factory pattern.
+ */
+export function loadModuleRegistry(): ModuleRegistry {
+  const registry = new ModuleRegistry()
+  // Descriptors will be registered here as specs are migrated.
+  return registry
+}
+
 function loadSpecifications() {
   const configModuleSpecs = [
     appAccessSpec,

packages/app/src/cli/services/generate/fetch-extension-specifications.ts

@@ -60,6 +60,7 @@ export async function fetchSpecifications({
   return [...updatedSpecs]
 }
 
+
 async function mergeLocalAndRemoteSpecs(
   local: ExtensionSpecification[],
   remote: RemoteSpecification[],