html2apk 0.1.0

package/README.md

@@ -0,0 +1,472 @@
+# html2apk
+
+`html2apk` transforma uma pasta com HTML, CSS, JS e assets em um APK Android usando Cordova.
+
+Use ele quando voce ja tem um app web, por exemplo uma pasta com `index.html`, `style.css`, `app.js` e imagens, e quer gerar um `.apk` instalavel no Android.
+
+## O Mais Importante
+
+Na pratica, voce vai usar estes comandos:
+
+```bash
+html2apk init
+html2apk doctor
+html2apk build
+```
+
+`doctor` e `build` fazem coisas diferentes:
+
+| Comando | O que faz | Quando usar |
+| --- | --- | --- |
+| `html2apk doctor` | Confere se o computador esta pronto para gerar APK. Ele verifica Java, Gradle, Cordova e Android SDK. | Use antes do primeiro build, depois de instalar ferramentas Android ou quando o build falhar por ambiente. |
+| `html2apk build` | Gera o APK de verdade a partir da sua pasta HTML. | Use quando o `doctor` estiver OK e voce quiser criar/atualizar o APK. |
+
+O `doctor` nao gera APK. Ele so diagnostica o ambiente.
+
+O `build` gera APK. Ele cria um projeto Cordova temporario, copia seu HTML/CSS/JS, compila Android e salva o resultado em `dist/`.
+
+## Instalar
+
+Se estiver usando como pacote global:
+
+```bash
+npm install -g html2apk
+```
+
+Durante desenvolvimento deste repositorio:
+
+```bash
+npm install
+npm link
+```
+
+Tambem da para rodar localmente sem link:
+
+```bash
+node bin/html2apk.js doctor
+node bin/html2apk.js build
+```
+
+## Requisitos Do Computador
+
+Para gerar APK, o computador precisa ter:
+
+- Node.js 18 ou superior
+- JDK
+- Android SDK ou Android Studio
+- Android command line tools
+- Gradle
+- Cordova CLI
+
+Este projeto usa `cordova-android@15.0.0` por padrao. Por isso, o Android SDK precisa ter:
+
+- Android Platform 36
+- Android Build Tools 36.0.0
+
+Com `sdkmanager`, os pacotes principais sao:
+
+```bash
+sdkmanager "platform-tools" "platforms;android-36" "build-tools;36.0.0"
+```
+
+Variaveis de ambiente comuns:
+
+```bash
+export JAVA_HOME=/path/to/jdk
+export ANDROID_HOME=/path/to/android-sdk
+export ANDROID_SDK_ROOT=/path/to/android-sdk
+```
+
+No Windows, o `html2apk doctor` tenta encontrar automaticamente o SDK em:
+
+```text
+C:\Users\SEU_USUARIO\AppData\Local\Android\Sdk
+```
+
+## Passo A Passo
+
+Entre na pasta do seu app web:
+
+```bash
+cd caminho/da/minha-pasta-html
+```
+
+Sua pasta deve ter pelo menos um arquivo de entrada, normalmente:
+
+```text
+index.html
+```
+
+Crie a configuracao inicial:
+
+```bash
+html2apk init
+```
+
+Esse comando cria dois arquivos quando eles ainda nao existem:
+
+- `app.json`
+- `index.html`
+
+Edite o `app.json` com o nome do app, pacote Android e preferencias.
+
+Depois confira o ambiente:
+
+```bash
+html2apk doctor
+```
+
+Se tudo aparecer como `OK`, gere o APK:
+
+```bash
+html2apk build
+```
+
+O arquivo final sera criado em:
+
+```text
+dist/NomeDoApp-1.0.0-debug.apk
+```
+
+## Comandos Da CLI
+
+### `html2apk init`
+
+Cria uma configuracao inicial para seu app.
+
+Use quando voce ainda nao tem `app.json`:
+
+```bash
+html2apk init
+```
+
+Ele nao apaga seu `app.json` nem seu `index.html` se eles ja existirem.
+
+### `html2apk doctor`
+
+Verifica se o computador esta pronto para compilar Android:
+
+```bash
+html2apk doctor
+```
+
+Exemplo de saida boa:
+
+```text
+OK  java
+OK  javac
+OK  gradle
+OK  cordova
+OK  Android build-tools 36.0.0
+OK  Android platform android-36
+Environment looks ready.
+```
+
+Se aparecer `ERR`, resolva esse item antes de rodar `build`.
+
+### `html2apk build`
+
+Gera o APK:
+
+```bash
+html2apk build
+```
+
+Opcoes comuns:
+
+```bash
+html2apk build --debug
+html2apk build --release
+html2apk build --mode fullscreen
+html2apk build --mode standalone
+html2apk build --entry-file index.html
+html2apk build --web-root .
+html2apk build --app-name MeuApp
+html2apk build --package-id com.seuapp.meuapp
+html2apk build --android-platform android@15.0.0
+```
+
+Com `--debug`, a pasta Cordova temporaria fica salva para inspecao caso voce queira investigar arquivos gerados.
+
+Sem `--debug`, a pasta temporaria e limpa no fim do build.
+
+## Configuracao Com `app.json`
+
+O `app.json` fica na raiz do seu app. Se ele nao existir, `config.json` e usado como fallback.
+
+Exemplo completo:
+
+```json
+{
+  "_editMe": "Edite os campos abaixo e rode: html2apk doctor && html2apk build",
+  "appName": "MeuApp",
+  "packageId": "com.seuapp.meuapp",
+  "version": "1.0.0",
+  "mode": "fullscreen",
+  "icon": "",
+  "splash": "",
+  "permissions": ["INTERNET", "CAMERA", "POST_NOTIFICATIONS", "VIBRATE"],
+  "plugins": ["cordova-plugin-camera"],
+  "release": false,
+  "androidPlatform": "android@15.0.0",
+  "keystore": {
+    "path": "",
+    "alias": "app",
+    "storePassword": "",
+    "keyPassword": ""
+  },
+  "debug": false,
+  "entryFile": "index.html",
+  "webRoot": ".",
+  "files": []
+}
+```
+
+Campos principais:
+
+| Campo | Para que serve |
+| --- | --- |
+| `appName` | Nome visivel do app. |
+| `packageId` | Identificador Android. Precisa ter formato como `com.empresa.app`. |
+| `version` | Versao do app. |
+| `mode` | `fullscreen` para tela cheia ou `standalone` para modo normal. |
+| `entryFile` | Arquivo HTML inicial. Normalmente `index.html`. |
+| `webRoot` | Pasta onde estao os arquivos web. Normalmente `"."`. |
+| `permissions` | Permissoes Android adicionadas ao app. |
+| `plugins` | Plugins Cordova extras. |
+| `androidPlatform` | Versao da plataforma Cordova Android. Padrao: `android@15.0.0`. |
+| `debug` | Se `true`, preserva a pasta temporaria de build. |
+| `release` | Se `true`, gera build release. |
+| `keystore` | Dados de assinatura para build release. |
+
+Prioridade de configuracao:
+
+1. Opcoes passadas na CLI ou em `buildApk`.
+2. `app.json` ou `config.json`.
+3. Valores padrao do html2apk.
+
+## Exemplo Minimo
+
+Este repositorio ja inclui um exemplo em:
+
+```text
+examples/minimal
+```
+
+Para testar:
+
+```bash
+cd examples/minimal
+node ../../bin/html2apk.js doctor
+node ../../bin/html2apk.js build
+```
+
+O APK sai em:
+
+```text
+examples/minimal/dist/
+```
+
+## Usando Como Biblioteca
+
+Tambem e possivel usar pelo Node.js:
+
+```js
+const { buildApk } = require("html2apk");
+
+const result = await buildApk();
+console.log(result.apkPath);
+```
+
+Com opcoes:
+
+```js
+const result = await buildApk({
+  mode: "fullscreen",
+  release: true
+});
+```
+
+Retorno:
+
+```json
+{
+  "apkPath": "/app/dist/MeuApp-1.0.0-debug.apk",
+  "buildDir": null,
+  "logs": [],
+  "status": "success",
+  "tempCleaned": true
+}
+```
+
+## Bridge Nativa
+
+A v0.1 instala um plugin Cordova local com uma API global simples para recursos Android.
+
+No seu JavaScript do app:
+
+```js
+await solicitarPermissaoNotificacoes();
+
+toast("Mensagem");
+vibrar(250);
+
+notificar({
+  titulo: "Pedido aprovado",
+  texto: "Toque para abrir os detalhes",
+  aoClicar: {
+    acao: "abrir-rota",
+    rota: "/pedido/123",
+    dados: { id: 123 }
+  }
+});
+
+agendarNotificacao({
+  titulo: "Lembrete",
+  texto: "Hora de abrir o app",
+  quando: Date.now() + 60000,
+  aoClicar: {
+    acao: "abrir-rota",
+    rota: "/lembretes"
+  }
+});
+
+fullscreen(true);
+```
+
+Clique em notificacao:
+
+```js
+aoClicarNotificacao((evento) => {
+  console.log(evento.id, evento.aoClicar || evento.onClick);
+});
+
+window.addEventListener("html2apk:notification", (event) => {
+  console.log(event.detail);
+});
+
+const inicial = await obterNotificacaoInicial();
+```
+
+Permissoes e alarmes:
+
+```js
+const status = await statusPermissaoNotificacoes();
+if (!status.granted) {
+  await solicitarPermissaoNotificacoes();
+}
+
+const podeUsarAlarmeExato = await podeAgendarNotificacaoExata();
+if (!podeUsarAlarmeExato) {
+  await abrirConfiguracaoAlarmeExato();
+}
+```
+
+A bridge cria canal de notificacao, solicita/consulta `POST_NOTIFICATIONS` no Android 13+, abre o app com payload quando a notificacao e clicada, persiste notificacoes agendadas e tenta reagendar apos reboot ou update do app.
+
+## Problemas Comuns
+
+### `doctor` mostra `ERR java` ou `ERR javac`
+
+Instale um JDK e configure `JAVA_HOME`.
+
+### `doctor` mostra erro no Android SDK
+
+Instale Android Studio ou Android command line tools. Depois instale:
+
+```bash
+sdkmanager "platform-tools" "platforms;android-36" "build-tools;36.0.0"
+```
+
+### `build` diz que nao encontrou `index.html`
+
+Confira `entryFile` e `webRoot` no `app.json`.
+
+Exemplo:
+
+```json
+{
+  "entryFile": "index.html",
+  "webRoot": "."
+}
+```
+
+Se seu HTML fica em `public/index.html`:
+
+```json
+{
+  "entryFile": "index.html",
+  "webRoot": "public"
+}
+```
+
+### Quero ver a pasta Cordova gerada
+
+Rode:
+
+```bash
+html2apk build --debug
+```
+
+No fim, a CLI mostra o caminho da pasta temporaria.
+
+### O APK foi gerado, onde ele esta?
+
+Por padrao:
+
+```text
+dist/
+```
+
+Exemplo:
+
+```text
+dist/MeuApp-1.0.0-debug.apk
+```
+
+## Interface Visual Para Windows
+
+Tambem existe um app visual em Electron. O usuario abre o `html2apk.exe`, escolhe o idioma na primeira execucao, arrasta a pasta do projeto e acompanha tudo pela interface.
+
+Fluxo da interface:
+
+1. Arraste ou escolha a pasta do projeto.
+2. O app mostra `verificando ambiente` antes de liberar as proximas etapas.
+3. Se faltarem pacotes do Android SDK, ele pede permissao e tenta baixar/instalar mostrando logs.
+4. Preencha as configuracoes obrigatorias: nome do app, Package ID, versao, modo e icone PNG.
+5. Revise, clique em `Gerar APK` e acompanhe a barra de progresso.
+6. Ao concluir, a tela final mostra o APK gerado e botoes para abrir a pasta `dist` ou localizar o arquivo.
+
+O PNG escolhido e usado como icone do aplicativo e tambem como imagem da tela inicial do Android, evitando o splash padrao do Cordova.
+
+Os logs podem ser abertos em uma barra inferior durante qualquer etapa pelo botao `Mostrar logs`. Se atrapalhar a visualizacao, use `Ocultar logs` e a area principal volta a ocupar a altura da janela.
+
+Para rodar a interface em desenvolvimento:
+
+```bash
+npm run desktop
+```
+
+Para gerar o executavel portatil do Windows:
+
+```bash
+npm run build-desktop-win
+```
+
+O resultado fica em:
+
+```text
+dist-desktop/html2apk-portable/html2apk.exe
+```
+
+Esse portatil inclui a interface, o `html2apk`, Cordova e as dependencias Node do projeto. JDK, Gradle e Android SDK sao ferramentas grandes do sistema; quando possivel, a interface tenta completar os pacotes Android com permissao do usuario.
+
+## Executavel Da CLI
+
+O projeto tambem mantem scripts antigos para empacotar somente a CLI com `pkg`:
+
+```bash
+npm run build-win
+npm run build-linux
+npm run build-mac
+```

package/bin/html2apk-desktop.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+"use strict";
+
+const path = require("path");
+const { spawn } = require("child_process");
+const electron = require("electron");
+
+const env = { ...process.env };
+delete env.ELECTRON_RUN_AS_NODE;
+
+const child = spawn(electron, [path.resolve(__dirname, "..", "src", "desktop", "main.js")], {
+  env,
+  stdio: "inherit",
+  windowsHide: false
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code || 0);
+});

package/bin/html2apk.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+"use strict";
+
+const { runCli } = require("../src/cli");
+
+runCli(process.argv.slice(2)).catch((error) => {
+  const message = error && error.stack ? error.stack : String(error);
+  console.error(message);
+  if (error && Array.isArray(error.logs) && error.logs.length > 0) {
+    console.error("\nhtml2apk logs:");
+    for (const line of error.logs) {
+      console.error(line);
+    }
+  }
+  if (error && error.buildDir) {
+    console.error(`\nBuild directory kept: ${error.buildDir}`);
+  }
+  process.exitCode = 1;
+});

package/examples/minimal/app.json

@@ -0,0 +1,27 @@
+{
+  "_editMe": "Edite os campos abaixo e rode: html2apk doctor && html2apk build",
+  "appName": "MeuApp",
+  "packageId": "com.seuapp.meuapp",
+  "version": "1.0.0",
+  "mode": "fullscreen",
+  "icon": "",
+  "splash": "",
+  "permissions": [
+    "INTERNET",
+    "POST_NOTIFICATIONS",
+    "VIBRATE"
+  ],
+  "plugins": [],
+  "release": false,
+  "androidPlatform": "android@15.0.0",
+  "keystore": {
+    "path": "",
+    "alias": "",
+    "storePassword": "",
+    "keyPassword": ""
+  },
+  "debug": false,
+  "entryFile": "index.html",
+  "webRoot": ".",
+  "files": []
+}

package/examples/minimal/index.html

@@ -0,0 +1,41 @@
+<!doctype html>
+<html lang="pt-BR">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>MeuApp</title>
+  <style>
+    body {
+      min-height: 100vh;
+      margin: 0;
+      display: grid;
+      place-items: center;
+      font-family: system-ui, sans-serif;
+      background: #101820;
+      color: white;
+    }
+
+    main {
+      width: min(92vw, 420px);
+      display: grid;
+      gap: 12px;
+    }
+
+    button {
+      min-height: 44px;
+      border: 0;
+      border-radius: 8px;
+      font: inherit;
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>MeuApp</h1>
+    <button onclick="toast('Ola do Android')">Toast</button>
+    <button onclick="vibrar(250)">Vibrar</button>
+    <button onclick="notificar('Gerada pelo html2apk')">Notificar agora</button>
+  </main>
+  <script src="cordova.js"></script>
+</body>
+</html>

package/index.js

@@ -0,0 +1,3 @@
+"use strict";
+
+module.exports = require("./src");

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "html2apk",
+  "version": "0.1.0",
+  "description": "Node CLI and library to turn an HTML/CSS/JS folder into an Android APK through Cordova.",
+  "main": "index.js",
+  "bin": {
+    "html2apk": "./bin/html2apk.js"
+  },
+  "type": "commonjs",
+  "license": "MIT",
+  "files": [
+    "bin",
+    "src",
+    "examples",
+    "index.js",
+    "html2apk.png",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node bin/html2apk.js build",
+    "doctor": "node bin/html2apk.js doctor",
+    "desktop": "node bin/html2apk-desktop.js",
+    "build-desktop-win": "node scripts/build-desktop-portable.js",
+    "test": "node --test",
+    "build-win": "pkg . --targets node20-win-x64 --output dist/html2apk.exe",
+    "build-linux": "pkg . --targets node20-linux-x64 --output dist/html2apk-linux",
+    "build-mac": "pkg . --targets node20-macos-x64 --output dist/html2apk-macos"
+  },
+  "pkg": {
+    "scripts": [
+      "src/**/*.js"
+    ],
+    "assets": [
+      "src/templates/**/*"
+    ]
+  },
+  "build": {
+    "appId": "dev.caiomultiversando.html2apk",
+    "productName": "html2apk",
+    "copyright": "Copyright © Dev Caio Multiversando",
+    "asar": false,
+    "directories": {
+      "output": "dist-desktop"
+    },
+    "files": [
+      "bin/**/*",
+      "src/**/*",
+      "index.js",
+      "package.json",
+      "package-lock.json",
+      "README.md",
+      "html2apk.png",
+      "node_modules/**/*"
+    ],
+    "extraMetadata": {
+      "main": "src/desktop/main.js"
+    },
+    "win": {
+      "target": [
+        "portable"
+      ],
+      "icon": "html2apk.png"
+    }
+  },
+  "devDependencies": {
+    "electron": "^42.3.0",
+    "electron-builder": "^26.8.1",
+    "pkg": "^5.8.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "cordova": "^13.0.0"
+  }
+}

package/src/android/README.md

@@ -0,0 +1,7 @@
+# Android Native Layer
+
+The production Android implementation is generated as a local Cordova plugin from:
+
+`src/templates/cordova-plugin-html2apk-bridge/src/android`
+
+Keeping the Android source inside the template lets each build copy a self-contained plugin into the temporary Cordova project. This directory exists as the top-level Android ownership boundary for future native modules, build hooks, signing helpers, and Android-specific orchestration.

package/src/bridge/install-bridge.js

@@ -0,0 +1,16 @@
+"use strict";
+
+const path = require("path");
+const { copyDirectory, removePath } = require("../utils/fs-extra");
+
+async function installBridgePlugin(buildDir) {
+  const source = path.resolve(__dirname, "..", "templates", "cordova-plugin-html2apk-bridge");
+  const destination = path.join(buildDir, "html2apk-bridge-plugin");
+  await removePath(destination);
+  await copyDirectory(source, destination, () => false);
+  return destination;
+}
+
+module.exports = {
+  installBridgePlugin
+};