@open-mova/cli 0.1.20 → 0.1.21

package/README.md

@@ -10,14 +10,19 @@ El CLI descarga la shell, el core y la plantilla de microfrontales desde tags es
 
 ## Índice de comandos
 
+- [`mova --help` y `mova --version`](#mova---help-y-mova---version)
 - [`mova create`](#mova-create)
+- [`mova mf`](#mova-mf)
 - [`mova mf create`](#mova-mf-create)
 - [`mova mf add`](#mova-mf-add)
 - [`mova start`](#mova-start)
 - [`mova build`](#mova-build)
 - [`mova info`](#mova-info)
+- [`mova doctor`](#mova-doctor)
 - [`mova update`](#mova-update)
+- [`mova shell`](#mova-shell)
 - [`mova shell versions`](#mova-shell-versions)
+- [`mova cap`](#mova-cap)
 - [`mova cap add`](#mova-cap-add)
 - [`mova cap sync`](#mova-cap-sync)
 - [`mova cap open`](#mova-cap-open)
@@ -47,6 +52,17 @@ npm link
 
 ## Comandos
 
+### `mova --help` y `mova --version`
+
+Muestra la ayuda del CLI o la versión instalada.
+
+```bash
+mova --help
+mova --version
+mova mf --help
+mova cap --help
+```
+
 ### `mova create`
 
 Crea una aplicación completa. Descarga una shell versionada, el core y un MF
@@ -63,6 +79,11 @@ mova create mi-aplicacion --empty
 
 Sin `--shell-version` se usa el tag estable más reciente (`vMAJOR.MINOR.PATCH`). `--empty` omite el MF inicial.
 
+### `mova mf`
+
+Es el grupo de comandos para crear y registrar microfrontales en la aplicación.
+Usa `mova mf --help` para consultar sus subcomandos.
+
 ### `mova mf create`
 
 Crea un microfrontal local, lo registra y actualiza la configuración de federación de la shell.
@@ -97,6 +118,32 @@ mova mf add --name catalog --route productos \
 
 El CLI actualiza `mova.config.json`, `src/assets/federation.manifest.json` y `src/app/application.config.ts`.
 
+Para un MF remoto que no tenga un proyecto local, declara explícitamente su
+rango de Core:
+
+```bash
+mova mf add --name catalog --route catalog \
+  --remote catalog-microfrontend \
+  --remote-entry https://cdn.example.com/catalog/remoteEntry.json \
+  --core-version '^0.2.2'
+```
+
+### `mova mf update`
+
+Actualiza un MF local que fue creado desde una plantilla de Open Mova. Compara
+la plantilla original, el proyecto actual y la nueva versión en tres pasos:
+solo aplica cambios que no hayan sido personalizados y deja los conflictos
+para revisión.
+
+```bash
+mova mf update home --check
+mova mf update home --to v0.2.2
+```
+
+El comando conserva el nombre, la ruta, el puerto, el perfil y las
+dependencias propias del proveedor. Si cambia `package.json`, elimina el
+lockfile para que ejecutes `npm install` en el MF.
+
 ### `mova start`
 
 Arranca los MFs locales registrados y después la shell. Los MFs configurados solo con una URL remota no se arrancan localmente.
@@ -122,6 +169,25 @@ Muestra la aplicación detectada, la versión de shell y sus microfrontales. Tam
 mova info
 ```
 
+### `mova doctor`
+
+Diagnostica el entorno de desarrollo y la aplicación encontrada desde el
+directorio actual. Comprueba las herramientas básicas, las dependencias, la
+configuración de la shell y los microfrontales, las URLs de producción y la
+compatibilidad de Core.
+
+Si la aplicación contiene plataformas Capacitor, también revisa los
+requisitos disponibles de Android o iOS, como el SDK, `adb`, emuladores,
+Xcode, CocoaPods, claves y descripciones de permisos.
+
+```bash
+mova doctor
+```
+
+Los avisos informan de elementos opcionales o todavía no configurados. Los
+errores hacen que el comando termine con un código distinto de cero, por lo
+que también puede utilizarse en scripts de validación.
+
 ### `mova update`
 
 Actualiza los archivos técnicos de la shell usando como referencia el tag con
@@ -147,9 +213,16 @@ Lista los tags estables disponibles para crear aplicaciones.
 mova shell versions
 ```
 
+### `mova shell`
+
+Es el grupo de comandos relacionado con las versiones de la shell. Actualmente
+su subcomando disponible es `mova shell versions`.
+
 ### `mova cap add`
 
-Compila la aplicación y añade una plataforma nativa. Configura antes el `appId` definitivo en `capacitor.config.ts`.
+Compila la shell, añade una plataforma nativa y aplica su configuración inicial.
+El `appId` y el `appName` se generan al crear la aplicación; revísalos en
+`capacitor.config.ts` si necesitas personalizarlos antes de distribuirla.
 
 ```bash
 mova cap add android
@@ -198,6 +271,11 @@ mova cap open android
 mova cap open ios
 ```
 
+### `mova cap`
+
+Es el grupo de comandos para preparar y abrir los proyectos nativos de
+Capacitor. Sus subcomandos son `add`, `sync` y `open`.
+
 ## Flujo habitual
 
 ```bash
@@ -210,6 +288,98 @@ mova start
 
 Los microfrontales siempre se cargan remotamente mediante Native Federation. En producción, cada MF debe estar publicado en HTTPS y registrado con su `productionRemoteEntry`. Capacitor no copia los MFs al paquete nativo: la shell los carga desde sus URLs en ejecución.
 
-## Limitaciones actuales
+## Flujo para Android
+
+> [!WARNING]
+> Antes de empezar debes tener instalado Android Studio, el Android SDK, las
+> Build Tools, Platform Tools (`adb`) y un emulador o un dispositivo Android.
+> También necesitas Node.js 22, npm y Git. Android Studio incluye un JDK
+> compatible, por lo que normalmente no necesitas instalar otro manualmente.
+
+Desde el directorio donde quieras crear la aplicación:
+
+```bash
+mova create mi-aplicacion
+cd mi-aplicacion
+npm install
+npm --prefix mfs/home install
+```
+
+Comprueba que cada microfrontal tiene un `productionRemoteEntry` HTTPS en
+`mova.config.json`. Android no puede utilizar las URLs de desarrollo de
+`localhost` como si fuera el navegador del ordenador.
+
+Añade la plataforma Android. El comando compila la shell, ejecuta Capacitor y
+aplica la configuración específica de los plugins instalados:
+
+```bash
+mova cap add android
+```
+
+Si utilizas Google Maps, proporciona la clave antes de sincronizar:
+
+```bash
+OPEN_MOVA_GOOGLE_MAPS_ANDROID_API_KEY=tu_clave mova cap sync android
+```
+
+También puedes guardarla en `mova.config.json`, como se explica en la sección
+[`mova cap sync`](#mova-cap-sync). Para volver a sincronizar después de
+cambiar la shell, los plugins o la configuración:
+
+```bash
+mova cap sync android
+```
+
+Abre el proyecto nativo en Android Studio:
+
+```bash
+mova cap open android
+```
+
+En Android Studio selecciona un emulador o dispositivo, espera a que termine
+la sincronización de Gradle y pulsa **Run**. Para probar una nueva versión del
+MF remoto no hace falta recompilar Android si la URL publicada no cambia; la
+shell lo cargará al iniciar la aplicación.
+
+## Flujo para iOS
+
+> [!WARNING]
+> Antes de empezar debes tener instalado Xcode, sus Command Line Tools y
+> CocoaPods. Necesitas macOS, Node.js 22, npm y Git. Para ejecutar la app en un
+> dispositivo físico necesitarás también una cuenta de Apple y la firma
+> configurada en Xcode; el simulador no requiere un dispositivo registrado.
+
+Desde el directorio donde quieras crear la aplicación:
+
+```bash
+mova create mi-aplicacion
+cd mi-aplicacion
+npm install
+npm --prefix mfs/home install
+```
+
+Comprueba que cada microfrontal tiene un `productionRemoteEntry` HTTPS en
+`mova.config.json`. La aplicación iOS seguirá cargando esos microfrontales
+remotos desde la shell; no se copian dentro del proyecto nativo.
+
+Añade y sincroniza la plataforma iOS:
+
+```bash
+mova cap add ios
+mova cap sync ios
+```
+
+Revisa en Xcode los permisos y la configuración nativa que necesiten los
+plugins utilizados, por ejemplo las descripciones de cámara, fotos,
+geolocalización o notificaciones en `Info.plist` y los entitlements
+correspondientes.
+
+Abre el proyecto en Xcode:
+
+```bash
+mova cap open ios
+```
 
-El CLI todavía no actualiza automáticamente la shell de una aplicación creada ni publica microfrontales. Los comandos móviles requieren una versión de shell que incluya Capacitor.
+En Xcode selecciona un simulador o dispositivo, elige el esquema de la app y
+pulsa **Run**. Después de cambiar la shell o los plugins, ejecuta de nuevo
+`mova cap sync ios` antes de volver a abrir o ejecutar el proyecto.

package/dist/application/android-configuration.d.ts

@@ -0,0 +1,2 @@
+import type { OpenMovaApplicationConfiguration } from '../types.js';
+export declare function configureAndroidProject(applicationRoot: string, configuration: OpenMovaApplicationConfiguration): void;

package/dist/application/android-configuration.js

@@ -0,0 +1,90 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export function configureAndroidProject(applicationRoot, configuration) {
+    const packageConfiguration = readPackageConfiguration(applicationRoot);
+    configureMinimumSdk(applicationRoot, packageConfiguration);
+    configureBackgroundRunner(applicationRoot, packageConfiguration);
+    configureGoogleMaps(applicationRoot, configuration, packageConfiguration);
+}
+function configureGoogleMaps(applicationRoot, configuration, packageConfiguration) {
+    if (!packageConfiguration.dependencies?.['@capacitor/google-maps'])
+        return;
+    const manifestPath = join(applicationRoot, 'android', 'app', 'src', 'main', 'AndroidManifest.xml');
+    if (!existsSync(manifestPath)) {
+        throw new Error('No se encuentra AndroidManifest.xml para configurar Google Maps.');
+    }
+    const manifest = readFileSync(manifestPath, 'utf8');
+    const apiKeyMetadata = 'android:name="com.google.android.geo.API_KEY"';
+    if (!manifest.includes(apiKeyMetadata)) {
+        const applicationCloseTag = '</application>';
+        if (!manifest.includes(applicationCloseTag)) {
+            throw new Error('No se ha encontrado el elemento application en AndroidManifest.xml.');
+        }
+        const metadata = [
+            '        <meta-data',
+            `            ${apiKeyMetadata}`,
+            '            android:value="@string/open_mova_google_maps_api_key" />',
+        ].join('\n');
+        writeFileSync(manifestPath, manifest.replace(applicationCloseTag, `${metadata}\n    ${applicationCloseTag}`), 'utf8');
+    }
+    const valuesDirectory = join(applicationRoot, 'android', 'app', 'src', 'main', 'res', 'values');
+    mkdirSync(valuesDirectory, { recursive: true });
+    const apiKey = process.env['OPEN_MOVA_GOOGLE_MAPS_ANDROID_API_KEY'] ??
+        configuration.native?.googleMaps?.androidApiKey ??
+        // Google Maps aborta la aplicación si falta por completo esta entrada.
+        'OPEN_MOVA_GOOGLE_MAPS_API_KEY_NOT_CONFIGURED';
+    const resource = [
+        '<?xml version="1.0" encoding="utf-8"?>',
+        '<resources>',
+        `    <string name="open_mova_google_maps_api_key" translatable="false">${escapeXml(apiKey)}</string>`,
+        '</resources>',
+        '',
+    ].join('\n');
+    writeFileSync(join(valuesDirectory, 'open_mova_google_maps.xml'), resource, 'utf8');
+}
+function configureMinimumSdk(applicationRoot, packageConfiguration) {
+    if (!packageConfiguration.dependencies?.['@capacitor/local-llm'])
+        return;
+    const variablesPath = join(applicationRoot, 'android', 'variables.gradle');
+    if (!existsSync(variablesPath)) {
+        throw new Error('No se encuentra android/variables.gradle para configurar Local LLM.');
+    }
+    const variables = readFileSync(variablesPath, 'utf8');
+    const minimumSdkPattern = /minSdkVersion\s*=\s*(\d+)/;
+    const currentMinimumSdk = Number(minimumSdkPattern.exec(variables)?.[1]);
+    if (!Number.isFinite(currentMinimumSdk)) {
+        throw new Error('No se ha encontrado minSdkVersion en android/variables.gradle.');
+    }
+    if (currentMinimumSdk >= 28)
+        return;
+    writeFileSync(variablesPath, variables.replace(minimumSdkPattern, 'minSdkVersion = 28'), 'utf8');
+}
+function configureBackgroundRunner(applicationRoot, packageConfiguration) {
+    if (!packageConfiguration.dependencies?.['@capacitor/background-runner'])
+        return;
+    const gradlePath = join(applicationRoot, 'android', 'app', 'build.gradle');
+    if (!existsSync(gradlePath)) {
+        throw new Error('No se encuentra android/app/build.gradle para configurar Background Runner.');
+    }
+    const repositoryEntry = "dirs '../../node_modules/@capacitor/background-runner/android/src/main/libs', 'libs'";
+    const gradle = readFileSync(gradlePath, 'utf8');
+    if (gradle.includes(repositoryEntry))
+        return;
+    const flatDirectory = /flatDir\s*\{/;
+    if (!flatDirectory.test(gradle)) {
+        throw new Error('No se ha encontrado el bloque flatDir en android/app/build.gradle.');
+    }
+    writeFileSync(gradlePath, gradle.replace(flatDirectory, (match) => `${match}\n        ${repositoryEntry}`), 'utf8');
+}
+function readPackageConfiguration(applicationRoot) {
+    return JSON.parse(readFileSync(join(applicationRoot, 'package.json'), 'utf8'));
+}
+function escapeXml(value) {
+    return value.replace(/[&<>"']/g, (character) => ({
+        '&': '&amp;',
+        '<': '&lt;',
+        '>': '&gt;',
+        '"': '&quot;',
+        "'": '&apos;',
+    })[character] ?? character);
+}

package/dist/application/configuration-migrations.d.ts

@@ -0,0 +1,6 @@
+export declare const LATEST_CONFIGURATION_SCHEMA_VERSION = 2;
+export interface ConfigurationMigrationResult {
+    readonly value: unknown;
+    readonly migrations: readonly string[];
+}
+export declare function migrateConfiguration(value: unknown, applicationRoot: string): ConfigurationMigrationResult;

package/dist/application/configuration-migrations.js

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+export const LATEST_CONFIGURATION_SCHEMA_VERSION = 2;
+export function migrateConfiguration(value, applicationRoot) {
+    if (!isRecord(value) || typeof value.schemaVersion !== 'number') {
+        return { value, migrations: [] };
+    }
+    if (value.schemaVersion > LATEST_CONFIGURATION_SCHEMA_VERSION) {
+        throw new Error(`mova.config.json usa schemaVersion ${value.schemaVersion}, pero este CLI solo admite hasta ${LATEST_CONFIGURATION_SCHEMA_VERSION}.`);
+    }
+    let migrated = value;
+    const migrations = [];
+    if (migrated.schemaVersion === 1) {
+        migrated = migrateVersionOne(migrated, applicationRoot);
+        migrations.push('1 → 2: declarar la compatibilidad de Core de cada microfrontal');
+    }
+    return { value: migrated, migrations };
+}
+function migrateVersionOne(configuration, applicationRoot) {
+    const shellCoreVersion = readCoreVersion(join(applicationRoot, 'package.json'));
+    const microfrontends = Array.isArray(configuration.microfrontends)
+        ? configuration.microfrontends.map((entry) => {
+            if (!isRecord(entry))
+                return entry;
+            const sourcePath = typeof entry.sourcePath === 'string' ? entry.sourcePath : undefined;
+            const localCoreVersion = sourcePath
+                ? readCoreVersion(join(resolve(applicationRoot, sourcePath), 'package.json'))
+                : undefined;
+            const requiredCoreVersion = localCoreVersion ?? shellCoreVersion;
+            return {
+                ...entry,
+                // El comodín conserva aplicaciones antiguas cuyo remoto no tenía
+                // metadatos; se debe concretar al actualizar el MF.
+                compatibility: { requiredCoreVersion: requiredCoreVersion ?? '*' },
+            };
+        })
+        : configuration.microfrontends;
+    return {
+        ...configuration,
+        schemaVersion: 2,
+        microfrontends,
+    };
+}
+function readCoreVersion(packagePath) {
+    if (!existsSync(packagePath))
+        return undefined;
+    try {
+        const packageConfiguration = JSON.parse(readFileSync(packagePath, 'utf8'));
+        return packageConfiguration.dependencies?.['@open-mova/core'];
+    }
+    catch {
+        return undefined;
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}

package/dist/application/configuration.d.ts

@@ -1,7 +1,12 @@
 import type { MicrofrontendConfiguration, OpenMovaApplicationConfiguration } from '../types.js';
 export declare const APPLICATION_CONFIGURATION_FILE = "mova.config.json";
+export interface ApplicationConfigurationDocument {
+    readonly configuration: OpenMovaApplicationConfiguration;
+    readonly migrations: readonly string[];
+}
 export declare function findApplicationRoot(startDirectory: string): string | undefined;
 export declare function requireApplicationRoot(startDirectory: string): string;
 export declare function readApplicationConfiguration(applicationRoot: string): OpenMovaApplicationConfiguration;
+export declare function readApplicationConfigurationDocument(applicationRoot: string): ApplicationConfigurationDocument;
 export declare function writeApplicationConfiguration(applicationRoot: string, configuration: OpenMovaApplicationConfiguration): void;
 export declare function addMicrofrontend(configuration: OpenMovaApplicationConfiguration, microfrontend: MicrofrontendConfiguration): OpenMovaApplicationConfiguration;

package/dist/application/configuration.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
+import { LATEST_CONFIGURATION_SCHEMA_VERSION, migrateConfiguration, } from './configuration-migrations.js';
 export const APPLICATION_CONFIGURATION_FILE = 'mova.config.json';
 export function findApplicationRoot(startDirectory) {
     let currentDirectory = resolve(startDirectory);
@@ -22,17 +23,16 @@ export function requireApplicationRoot(startDirectory) {
     return applicationRoot;
 }
 export function readApplicationConfiguration(applicationRoot) {
+    return readApplicationConfigurationDocument(applicationRoot).configuration;
+}
+export function readApplicationConfigurationDocument(applicationRoot) {
     const configurationPath = join(applicationRoot, APPLICATION_CONFIGURATION_FILE);
-    try {
-        const parsed = JSON.parse(readFileSync(configurationPath, 'utf8'));
-        return validateApplicationConfiguration(parsed, configurationPath);
-    }
-    catch (error) {
-        if (error instanceof Error) {
-            throw error;
-        }
-        throw new Error(`No se ha podido leer ${configurationPath}.`);
-    }
+    const parsed = JSON.parse(readFileSync(configurationPath, 'utf8'));
+    const migration = migrateConfiguration(parsed, applicationRoot);
+    return {
+        configuration: validateApplicationConfiguration(migration.value, configurationPath),
+        migrations: migration.migrations,
+    };
 }
 export function writeApplicationConfiguration(applicationRoot, configuration) {
     const configurationPath = join(applicationRoot, APPLICATION_CONFIGURATION_FILE);
@@ -57,7 +57,8 @@ function validateApplicationConfiguration(value, configurationPath) {
     if (!isRecord(value)) {
         throw new Error(`${configurationPath} no contiene un objeto JSON válido.`);
     }
-    if (value.schemaVersion !== 1 || typeof value.name !== 'string') {
+    if (value.schemaVersion !== LATEST_CONFIGURATION_SCHEMA_VERSION ||
+        typeof value.name !== 'string') {
         throw new Error(`${configurationPath} no tiene el formato de Open Mova esperado.`);
     }
     if (!Array.isArray(value.microfrontends)) {
@@ -99,7 +100,7 @@ function validateApplicationConfiguration(value, configurationPath) {
     }
     const microfrontends = value.microfrontends.map((entry) => validateMicrofrontend(entry, configurationPath));
     return {
-        schemaVersion: 1,
+        schemaVersion: LATEST_CONFIGURATION_SCHEMA_VERSION,
         name: value.name,
         ...(shell ? { shell } : {}),
         ...(native ? { native } : {}),
@@ -130,12 +131,18 @@ function validateMicrofrontend(value, configurationPath) {
         typeof value.productionRemoteEntry !== 'string') {
         throw new Error(`${configurationPath} contiene una URL de producción no válida.`);
     }
-    if (value.template !== undefined && (!isRecord(value.template) ||
-        typeof value.template.repository !== 'string' ||
-        typeof value.template.version !== 'string' ||
-        typeof value.template.commit !== 'string' ||
-        value.template.project !== 'open-mova-mf-template' ||
-        (value.template.profile !== 'minimal' && value.template.profile !== 'demo'))) {
+    if (!isRecord(value.compatibility) ||
+        typeof value.compatibility.requiredCoreVersion !== 'string' ||
+        value.compatibility.requiredCoreVersion.trim() === '') {
+        throw new Error(`${configurationPath} contiene un microfrontal sin compatibilidad de Core declarada.`);
+    }
+    if (value.template !== undefined &&
+        (!isRecord(value.template) ||
+            typeof value.template.repository !== 'string' ||
+            typeof value.template.version !== 'string' ||
+            typeof value.template.commit !== 'string' ||
+            value.template.project !== 'open-mova-mf-template' ||
+            (value.template.profile !== 'minimal' && value.template.profile !== 'demo'))) {
         throw new Error(`${configurationPath} contiene una plantilla de microfrontal no válida.`);
     }
     return {
@@ -148,7 +155,12 @@ function validateMicrofrontend(value, configurationPath) {
             ? {}
             : { productionRemoteEntry: value.productionRemoteEntry }),
         ...(value.sourcePath === undefined ? {} : { sourcePath: value.sourcePath }),
-        ...(value.template === undefined ? {} : { template: value.template }),
+        compatibility: {
+            requiredCoreVersion: value.compatibility.requiredCoreVersion,
+        },
+        ...(value.template === undefined
+            ? {}
+            : { template: value.template }),
     };
 }
 function isRecord(value) {

package/dist/application/core-compatibility.d.ts

@@ -0,0 +1,3 @@
+import type { OpenMovaApplicationConfiguration } from '../types.js';
+export declare function areCoreRangesCompatible(first: string, second: string): boolean;
+export declare function findIncompatibleMicrofrontends(configuration: OpenMovaApplicationConfiguration, shellCoreVersion: string): readonly string[];

package/dist/application/core-compatibility.js

@@ -0,0 +1,10 @@
+import { intersects, validRange } from 'semver';
+export function areCoreRangesCompatible(first, second) {
+    return validRange(first) !== null && validRange(second) !== null && intersects(first, second);
+}
+export function findIncompatibleMicrofrontends(configuration, shellCoreVersion) {
+    return configuration.microfrontends
+        .filter((microfrontend) => !areCoreRangesCompatible(shellCoreVersion, microfrontend.compatibility.requiredCoreVersion))
+        .map((microfrontend) => `mova.config.json#microfrontends.${microfrontend.name}.compatibility ` +
+        `(shell ${shellCoreVersion}, MF ${microfrontend.compatibility.requiredCoreVersion})`);
+}

package/dist/application/doctor.d.ts

@@ -0,0 +1,12 @@
+export type DoctorCheckStatus = 'ok' | 'warning' | 'error';
+export interface DoctorCheck {
+    readonly id: string;
+    readonly status: DoctorCheckStatus;
+    readonly message: string;
+    readonly detail?: string;
+}
+export interface DoctorReport {
+    readonly applicationRoot?: string;
+    readonly checks: readonly DoctorCheck[];
+}
+export declare function inspectDevelopmentEnvironment(startDirectory: string): DoctorReport;