appmachine 0.0.2

package/README.md

@@ -0,0 +1,121 @@
+<p align="center" style="margin-top: 40px;">
+  <img src="https://raw.githubusercontent.com/max-matinpalo/appmachine/refs/heads/main/template/icon.png" alt="Project logo" width="160">
+</p>
+<br>
+
+
+# AppMachine
+
+**‼️ ATTENTON ‼️:** This package is not ready for mainstream use.  
+It’s meant as inspiration for advanced developers who want to automate their own
+build pipelines.
+
+**Personal motivation:** a fully automatic build flow for iOS + Android 🤖🧰  
+Configure once, one click trigger, download ready signed apps.  
+Never again waste time playing with Xcode, AndroidStudio and Capacitor.
+
+
+## Introduction
+
+AppMachine builds **signed native iOS and Android apps** for web apps.  
+It’s built on **Capacitor + GitHub Actions**. You trigger builds by pushing tags.  
+You don’t need to install any build tools on your own machine.
+
+## Install
+Inside your normal React project:
+
+```bash
+npm install appmachine
+npx appmachine
+```
+ Configure build variabels and secrets on github
+
+## Example usage
+1. git tag android; git push origin android
+2. github server builds app
+4. download ready app
+
+Builds are triggered by setting tags (ios, iosdev, android, androiddev).
+Because typically we only need to generate new ios/android apps rarely,
+only when native features change.
+
+
+## Base Config
+**Check out docs folder for detailed instruction for ios / android configs**
+
+| Type | Name | Description | Example |
+|---|---|---|---|
+| Variable | `APP_SERVER_URL` | Base URL where the app loads from | `https://app.example.com` |
+| Variable | `APP_ID` | iOS Bundle ID (App ID) | `com.company.app` |
+| Variable | `APP_NAME` | Visible app name | `ExampleApp` |
+
+
+## Android Configs
+| Type | Name | Description | Example |
+|---|---|---|---|
+| Secret | `ANDROID_KEYSTORE` | Base64 keystore from the keystore workflow | `BASE64...` |
+| Secret | `ANDROID_KEYSTORE_PASSWORD` | Keystore password used to sign the app | `password123` |
+
+## iOS Configs
+| Type | Name | Description | Example |
+|---|---|---|---|
+| Variable | `IOS_TEAM_ID` | Apple Developer Team ID | `A1B2C3D4E5` |
+| Secret | `IOS_CERT_BASE64` | Base64 of your **Distribution** `.p12` | `MII...` |
+| Secret | `IOS_CERT_PASSWORD` | Password for the `.p12` | `your-password` |
+| Secret | `IOS_PROFILE_BASE64` | Base64 of your `.mobileprovision` | `MII...` |
+
+
+---
+
+
+
+## How it works overview
+Trigger github action via tags (`iosdev`, `ios`, `androiddev` or`android`).
+
+The development and production builds only differs in used variabels and secrets.  
+Tag `iosdev` - use the variables of environment `Development`.  
+Tag `ios` - use variables of environment `Production`.
+
+1. **Capacitor setup** (same for iOS and Android)
+	- Installs Capacitor tooling
+	- Writes `capacitor.config.json` from GitHub Variables
+	- Generates native projects + assets with Capacitor
+	- Then runs iOS or Android specific signing
+2. **Setup signing**
+3. **Build**
+
+The easy step 1 is same for ios and android.
+
+At the moment, the build pipeline does **not** build your web app. Instead, it
+fetches the web app from a server. This means you must have the app deployed
+somewhere (for example Vercel).
+
+The reason: the “genius” way to ship apps is a **minimal native shell** with
+**OTA updates** and **offline support** via a service worker 😃
+
+If we want to make this package easier for junior developers, we should add an
+optional step to **build the web app during the pipeline** and ship the `dist`
+bundle inside the native app. This is very easy to add, and could be controlled
+with a workflow option/flag 😃
+
+
+
+## Native features
+
+In general, when we want code that runs on all platforms, we should prefer
+**Web APIs** whenever possible (camera, files, etc.). If a solid Web API exists,
+use it before reaching for native features.
+
+Not everything is available (or reliable) via Web APIs. For those cases, we use
+**Capacitor plugins**.
+
+This workflow installs the latest Capacitor packages on the build machine
+(`@capacitor/core`, `@capacitor/ios`, `@capacitor/android`, `@capacitor/cli`),
+so you don’t need to install them in your app.
+
+Example: if you want haptics, just install the plugin in your React project:
+
+```bash
+npm install @capacitor/haptics
+```
+

package/bin/install.js

@@ -0,0 +1,52 @@
+const fs = require('fs');
+const path = require('path');
+
+
+function die(msg) {
+	console.error("❌ " + msg);
+	process.exit(1);
+}
+
+
+// Recursively copies files or directories from source (s) to destination (d)
+function copy(s, d) {
+	const stat = fs.statSync(s);
+
+	// If it's a folder, ensure destination exists and copy all children
+	if (stat.isDirectory()) {
+		if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+		fs.readdirSync(s).forEach(f => copy(path.join(s, f), path.join(d, f)));
+		return;
+	}
+
+	// Otherwise, just copy the file
+	fs.copyFileSync(s, d);
+}
+
+
+// Main setup: moves GitHub workflows and AppMachine templates into the project root
+function install() {
+	const root = process.cwd();
+	const src = path.join(__dirname, '../src');
+	const dest = path.join(root, '.github/workflows');
+	const temp = path.join(__dirname, '../template');
+	const mach = path.join(root, 'appmachine');
+
+	// 1. Copy all .yml workflow files to .github/workflows
+	if (fs.existsSync(src)) {
+		if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+		fs.readdirSync(src).forEach(f => {
+			if (f.endsWith('.yml')) fs.copyFileSync(path.join(src, f), path.join(dest, f));
+		});
+	}
+
+	// 2. Recursively copy the template folder to /appmachine
+	if (fs.existsSync(temp)) copy(temp, mach);
+}
+
+
+try {
+	install();
+} catch (err) {
+	die(err.message || "Install failed");
+}

package/docs/android.md

@@ -0,0 +1,37 @@
+# AppMachine Android Build Workflow
+
+Build pipeline that turns your webapp into a **signed Android app**.
+
+
+## How it works
+1. Start a build by pushing tag `android` or `androiddev` on the branch you want to build.
+2. After workflow completes with success, download the app from workflow artifacts.
+3. Install the `.apk` to your Android phone or deploy the `.aab` to Google Play.
+
+The development and production builds only differ in used variables and secrets.
+Tag `androiddev` - use the variables of environment `Development`.
+Tag `android` - use variables of environment `Production`.
+
+The workflow will output the app in two formats: `.apk` and `.aab`
+The `.apk` format is for direct install/testing on devices.
+The `.aab` format is for upload to Google Play.
+
+
+
+## Setup
+1. Run ONCE the generate keystore workflow.
+   Only ONCE, because the keystore must stay equal when you deploy updates to your app.
+2. Store the keystore workflow result somewhere safe and add it as GitHub Environment
+   secrets: `ANDROID_KEYSTORE` (Base64) and `ANDROID_KEYSTORE_PASSWORD`.
+
+---
+
+## Required configuration (GitHub repo)
+
+| Type | Name | Description | Example |
+|---|---|---|---|
+| Variable | `APP_SERVER_URL` | Base URL where the app loads from | `https://app.example.com` |
+| Variable | `APP_ID` | Android App ID (package name) | `com.company.app` |
+| Variable | `APP_NAME` | Visible app name | `TeamFeedback` |
+| Secret | `ANDROID_KEYSTORE` | Base64 keystore from the keystore workflow | `BASE64...` |
+| Secret | `ANDROID_KEYSTORE_PASSWORD` | Keystore password used to sign the app | `password123` |

package/docs/ios.md

@@ -0,0 +1,112 @@
+# AppMachine iOS Build Workflow
+
+iOS build pipeline that turns your webapp into a **signed iOS `.ipa`** on **GitHub Actions**. No local Xcode needed.
+
+
+## How it works
+
+1. Setup Github Environemnt **Variables** + **Secrets**.
+2. Start a build by pushing tag `iosdev` or `ios`on the branch you want to build.
+3. After workflow completes with success, download app from workflow artifacts.
+4. Easiest way to upload app to apple is to use apple's **Transporter** app.
+   Download it from appstore, just drag & drop your .ipa file there and click upload.
+
+The development and production builds only differs in used variabels and secrets.
+Tag `iosdev` - use the variables of environment `Development`.
+Tag `ios` - use variables of environment `Production`.
+
+---
+
+## Required configuration (GitHub repo)
+
+| Type | Name | Description | Example |
+|---|---|---|---|
+| Variable | `APP_SERVER_URL` | Base URL where the app loads from | `https://app.example.com` |
+| Variable | `APP_ID` | iOS Bundle ID (App ID) | `com.company.app` |
+| Variable | `APP_NAME` | Visible app name | `TeamFeedback` |
+| Variable | `IOS_TEAM_ID` | Apple Developer Team ID | `A1B2C3D4E5` |
+| Secret | `IOS_CERT_BASE64` | Base64 of your **Distribution** `.p12` | `MII...` |
+| Secret | `IOS_CERT_PASSWORD` | Password for the `.p12` | `your-password` |
+| Secret | `IOS_PROFILE_BASE64` | Base64 of your `.mobileprovision` | `MII...` |
+
+---
+
+## Apple setup
+
+### 1) Create Bundle ID
+Create the bundle identifier you’ll ship as.
+
+- Apple Developer → **Certificates, Identifiers & Profiles**
+- **Identifiers** → `+` → **App IDs**
+- Set on github env `APP_ID` (example: `com.company.app`)
+
+### 2) Create App
+Create the app container in App Store Connect.
+
+- App Store Connect → **My Apps** → `+` → **New App**
+- Pick the same **Bundle ID** you created above
+
+### 3) Set IOS_TEAM_ID
+- Find your team id under Apple Developer → **Membership**
+- Copy it as repo variable `IOS_TEAM_ID` to github
+
+
+### 4) Distribution certificate
+If you don't have one yet, at the end of this document you find instruction how to make. Yes, stupid apple flow. Happily just once per year.
+
+Set github secret: `IOS_CERT_BASE64`
+By copying your certificate in base64 with
+base64 -i distribution.p12 | pbcopy
+
+
+### 5) Provisioning profile → `.mobileprovision`
+This ties together: **App ID + Distribution certificate**.
+
+- Apple Developer → Profiles → +
+- Choose **App Store** (distribution)
+- Select your **App ID**
+- Select your **Apple Distribution** certificate
+- Download the `.mobileprovision`
+
+**Convert to base64 (macOS) and copy to clipboard:**
+base64 -i Profile.mobileprovision | pbcopy
+
+
+
+## Apple Distribution certificate generation
+
+#### 1. Create the CSR on your Mac (Keychain Access) FIRST
+1. Open **Keychain Access**
+2. Menu: **Keychain Access → Certificate Assistant → Request a Certificate From a Certificate Authority…**
+3. Fill:
+	- **User Email Address**: your Apple ID email
+	- **Common Name**: e.g. `TeamFeedback Distribution`
+	- **CA Email Address**: leave empty
+4. Select:
+	- ✅ **Saved to disk**
+	- ✅ **Let me specify key pair information**
+5. Continue:
+	- Key size: **2048 bits**
+	- Algorithm: **RSA**
+6. Save the `.certSigningRequest` (CSR) file
+
+#### 2. Create the Distribution certificate in Apple Developer (upload the CSR)
+1. Apple Developer → **Certificates, Identifiers & Profiles**
+2. **Certificates** → `+`
+3. Choose **Apple Distribution**
+4. Upload the CSR you created above
+5. Download the generated certificate (`.cer`)
+
+#### 3. Install the `.cer` into Keychain
+1. Double-click the downloaded `.cer`
+2. In **Keychain Access**, find **Apple Distribution: ...**
+3. Expand it and confirm it has a **private key** under it
+
+#### 4. Export as `.p12`
+1. Right-click **Apple Distribution: ...** (the item that includes the private key)
+2. **Export…** → choose **.p12**
+3. Set an export password
+4. Save as `distribution.p12`
+
+#### 5. Convert `.p12` to base64 (macOS) and copy to clipboard
+base64 -i distribution.p12 | pbcopy

package/package.json

@@ -0,0 +1,10 @@
+{
+	"name": "appmachine",
+	"version": "0.0.2",
+	"description": "Native iOS/Android shell generator via GitHub Actions",
+	"author": "Max Matinpalo",
+	"type": "module",
+	"scripts": {
+		"install": "node ./scripts/install.js"
+	}
+}

package/src/android.yml

@@ -0,0 +1,125 @@
+name: AppMachine / Android
+on:
+  push:
+    tags: [androiddev, android]
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-22.04
+    environment: ${{ github.ref == 'refs/tags/androiddev' && 'Development' || 'Production' }}
+    env:
+      APP_SERVER_URL: ${{ vars.APP_SERVER_URL }}
+      APP_ID: ${{ vars.APP_ID }}
+      APP_NAME: ${{ vars.APP_NAME }}
+      ANDROID_KEYSTORE_BASE64: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
+      ANDROID_KEYSTORE_PASSWORD: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - uses: actions/setup-node@v4
+      with: { node-version: lts/*, cache: npm }
+
+    - uses: actions/setup-java@v4
+      with: { distribution: temurin, java-version: "21" }
+
+    - uses: android-actions/setup-android@v3
+
+    - name: 🔎 Preflight Checks
+      run: |
+        set -euo pipefail
+        req() { [ -n "${!1:-}" ] || { echo "❌ Missing: $1" >&2; exit 1; }; }
+        req APP_SERVER_URL; req APP_ID
+        req ANDROID_KEYSTORE_BASE64; req ANDROID_KEYSTORE_PASSWORD
+        echo "✅ All required variables and secrets are present."
+
+    - name: 📦 Install Dependencies
+      run: |
+        set -euo pipefail
+        [ -f package-lock.json ] && npm ci || npm install
+        npm i -D @capacitor/core @capacitor/cli @capacitor/android @capacitor/assets \
+          --no-save --no-package-lock --no-fund --no-audit
+
+    - name: ⚙️ Generate Config & WWW
+      run: |
+        set -euo pipefail
+        rm -rf www && mkdir -p www && cp -R appmachine/www/. www/
+        rm -f capacitor.config.*
+
+        node -e '
+          const fs = require("fs"), { URL } = require("url");
+          const raw = process.env.APP_SERVER_URL;
+          try { new URL(raw); } catch { console.error("❌ Invalid URL"); process.exit(1); }
+
+          const u = new URL(raw.replace(/\/$/, "")), host = u.hostname;
+          const cfg = {
+            appId: process.env.APP_ID,
+            appName: process.env.APP_NAME || "App",
+            webDir: "www",
+            server: { url: u.href, cleartext: true, allowNavigation: [host, "*." + host] }
+          };
+          fs.writeFileSync("capacitor.config.json", JSON.stringify(cfg, null, 2));
+        '
+
+    - name: 📱 Capacitor Sync & Assets
+      run: |
+        set -euo pipefail
+        rm -rf android && npx --no-install cap add android
+        mkdir -p assets
+        if [ -f "appmachine/icon.png" ]; then
+          echo "✅ Custom icon found"
+          for f in logo logo-dark splash splash-dark; do cp "appmachine/icon.png" "assets/$f.png"; done
+          npx --no-install capacitor-assets generate --android --assetPath assets
+        fi
+        npx --no-install cap sync android
+
+    - name: 🔐 Configure Signing
+      run: |
+        set -euo pipefail
+        printf '%s' "$ANDROID_KEYSTORE_BASE64" | tr -d '\n\r' | base64 -d > android/keystore.jks
+
+        cat > android/app/signing.gradle <<EOF
+        android {
+            signingConfigs {
+                release {
+                    storeFile file("../keystore.jks")
+                    storePassword System.getenv("ANDROID_KEYSTORE_PASSWORD")
+                    keyAlias "release"
+                    keyPassword System.getenv("ANDROID_KEYSTORE_PASSWORD")
+                }
+            }
+            buildTypes { release { signingConfig signingConfigs.release } }
+        }
+        EOF
+
+        node -e '
+          const fs = require("fs"), p = "android/app/build.gradle";
+          if (!fs.existsSync(p)) process.exit(1);
+          const s = fs.readFileSync(p, "utf8");
+          if (!s.includes("signing.gradle")) fs.appendFileSync(p, "\napply from: \"signing.gradle\"\n");
+        '
+
+    - name: 🏗️ Gradle Build
+      run: |
+        set -euo pipefail
+        chmod +x android/gradlew
+        (cd android && ./gradlew --no-daemon :app:bundleRelease :app:assembleRelease)
+
+    - name: 📂 Flatten Artifacts
+      run: |
+        mkdir -p dist
+        # Find files recursively and copy them to the flat 'dist' folder
+        find android/app/build/outputs -name "*.apk" -exec cp {} dist/ \;
+        find android/app/build/outputs -name "*.aab" -exec cp {} dist/ \;
+        
+        echo "✅ Contents of artifacts folder:"
+        ls -l dist/
+
+    - name: 📤 Upload Artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: android-release
+        path: dist/*

package/src/android_keygen.yml

@@ -0,0 +1,113 @@
+name: Generate Android Keystore
+
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "dev or prod"
+        required: true
+        type: choice
+        options: [dev, prod]
+      cn:
+        description: "Common Name"
+        required: true
+
+jobs:
+  preflight:
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.target == 'prod' && 'Production' || 'Development' }}
+    steps:
+      - name: 🛑 Safety Checks
+        shell: bash
+        env:
+          PASS: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
+          EXISTING_KEY: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
+        run: |
+          set -euo pipefail
+
+          if [ -z "$PASS" ]; then
+            echo "❌ Error: 'ANDROID_KEYSTORE_PASSWORD' secret is missing in this environment!"
+            exit 1
+          fi
+
+          if [ -n "$EXISTING_KEY" ]; then
+            echo "❌ Error: 'ANDROID_KEYSTORE_BASE64' secret is ALREADY set!"
+            echo "   -------------------------------------------------------------"
+            echo "   ⚠️ CRITICAL: You must use the same key to deploy updates."
+            exit 1
+          fi
+          echo "✅ Preflight passed."
+
+  gen:
+    needs: preflight
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.target == 'prod' && 'Production' || 'Development' }}
+
+    steps:
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "17"
+
+      - name: Generate base64
+        shell: bash
+        env:
+          PASS: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
+        run: |
+          set -euo pipefail
+
+          # Safety check
+          if [ -z "$PASS" ]; then echo "❌ Secret missing!"; exit 1; fi
+
+          TARGET='${{ inputs.target }}'
+          DNAME="CN=${{ inputs.cn }}"
+          ALIAS='release'
+          JKS="release-${TARGET}.jks"
+          OUT="keystore-${TARGET}.base64.txt"
+
+          # 1. Generate Key
+          keytool -genkeypair -v \
+            -keystore "$JKS" \
+            -storetype JKS \
+            -alias "$ALIAS" \
+            -keyalg RSA \
+            -keysize 2048 \
+            -validity 10000 \
+            -storepass "$PASS" \
+            -keypass "$PASS" \
+            -dname "$DNAME"
+
+          # 2. Encode
+          base64 -w0 "$JKS" > "$OUT"
+          echo >> "$OUT"
+
+          # 3. Security: Delete raw binary key immediately
+          rm -f "$JKS"
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: android-keystore-${{ inputs.target }}
+          path: keystore-${{ inputs.target }}.base64.txt
+          retention-days: 1
+
+      - name: 📝 Next steps
+        shell: bash
+        run: |
+          {
+            echo "## ✅ Next steps"
+            echo "1. Download the artifact **android-keystore-${{ inputs.target }}**."
+            echo "2. Copy the Base64 string."
+            echo "3. Save it as **ANDROID_KEYSTORE_BASE64** in the **${{ inputs.target == 'prod' && 'Production' || 'Development' }}** environment secrets."
+            echo ""
+            echo "## ⚠️ Backup"
+            echo "- Store the Base64 somewhere safe."
+            echo "- Artifact expires in **24h**."
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Cleanup Workspace
+        if: always()
+        shell: bash
+        run: |
+          set -euo pipefail
+          rm -f keystore-*.base64.txt