---
name: capacitor_build_apk
kind: pipeline
lang: bash
domain: pipelines
version: "1.0.0"
purity: impure
signature: "capacitor_build_apk(web_app_dir: string, [app_id: string], [app_name: string]) -> void"
description: "Pipeline que convierte una web app en un APK de Android usando Capacitor. Valida el entorno (ANDROID_HOME, Java 17+), construye el bundle web si no existe dist/, inicializa Capacitor si no está configurado, añade la plataforma Android, sincroniza y compila el APK con Gradle. El APK final queda en el directorio raíz de la web app."
tags: [android, apk, capacitor, mobile, build, pipeline, bash]
uses_functions:
  - install_android_sdk_bash_infra
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: []
params:
  - name: web_app_dir
    desc: "directorio raíz de la web app; debe contener package.json; si no existe dist/ se ejecuta pnpm build automáticamente"
  - name: app_id
    desc: "identificador de la app Android en formato reverse-DNS (default: com.fnregistry.app)"
  - name: app_name
    desc: "nombre visible de la app Android; si se omite, se lee del campo name de package.json"
output: "APK de debug en <web_app_dir>/<app_name>.apk; imprime ruta y tamaño en MB al finalizar"
tested: false
tests: []
test_file_path: ""
file_path: "bash/functions/pipelines/capacitor_build_apk.sh"
---

## Ejemplo

```bash
# Build con defaults (app-id y app-name desde package.json)
./bash/functions/pipelines/capacitor_build_apk.sh ~/projects/my-web-app

# Build especificando app-id y app-name
./bash/functions/pipelines/capacitor_build_apk.sh ~/projects/my-web-app \
  --app-id com.miempresa.miapp \
  --app-name "Mi Aplicación"
```

## Flujo

1. **Validación** — verifica que `web_app_dir` existe, tiene `package.json`, que `ANDROID_HOME` está seteado (o sourcea `$HOME/android-sdk/env.sh`) y que Java 17+ está disponible.
2. **Build web** — si no existe `dist/`, ejecuta `pnpm build` en el directorio de la app.
3. **Init Capacitor** — si no existe `capacitor.config.ts`, instala `@capacitor/core`, `@capacitor/cli` y `@capacitor/android` via npm y genera el archivo de configuración con el `appId`, `appName` y `webDir: dist`.
4. **Add Android** — si no existe el directorio `android/`, ejecuta `npx cap add android`.
5. **Sync** — ejecuta `npx cap sync android` para copiar los assets web al proyecto Android.
6. **Build APK** — ejecuta `./gradlew assembleDebug` desde `android/`; si falla sale con exit 1.
7. **Copia APK** — copia `android/app/build/outputs/apk/debug/app-debug.apk` a `<web_app_dir>/<app_name>.apk`.
8. **Resultado** — imprime la ruta del APK y su tamaño en MB.

## Requisitos

- **Node.js** y **pnpm** disponibles en PATH
- **Java 17+** disponible en PATH
- **Android SDK** instalado: `ANDROID_HOME` seteado, o bien `$HOME/android-sdk/env.sh` existente (generado por `install_android_sdk`)
- **Gradle wrapper** presente en el directorio `android/` (generado por `cap add android`)

## Notas

El pipeline usa `set -euo pipefail` — cualquier fallo detiene la ejecución inmediatamente.

El APK generado es un **debug build**, apto para desarrollo y pruebas. Para publicar en Play Store se necesita un release build firmado (`assembleRelease` con un keystore).

`install_android_sdk_bash_infra` se referencia como dependencia previa: el usuario debe haberlo ejecutado (o haber instalado el SDK manualmente) antes de invocar este pipeline.

La detección del `app_name` desde `package.json` usa `node -e` inline, lo que requiere que Node.js esté disponible. Si el campo `name` no existe en el JSON, se usa el valor por defecto `app`.

Para instalar el APK en un dispositivo Android conectado por USB (con depuración USB activada):

```bash
adb install <web_app_dir>/<app_name>.apk
```