npm package: @junaid-fts/expo-automation
Description: Expo Automation Framework
Latest version: 1.0.2

# 🚀 Expo Build Automation (Direct Execution)

> **Streamline your React Native build and submission workflow.**
> Automate Android & iOS builds and TestFlight submissions directly from your server.

---

## 📋 Overview

**Expo Build Automation** is a web-based tool designed to simplify the complex process of building and deploying Expo apps. 
Unlike dispersed CI/CD pipelines, this version runs **directly on your server**, giving you full control over the build environment and execution.

It abstracts away the command-line intricacies (EAS CLI), offering a user-friendly form to:
1.  **Generate/Clone** Expo apps.
2.  **inject** configuration and credentials dynamically.
3.  **Build & Submit** using the server's local resources.

## 🚀 User Guide

### How to Use the Application

1.  **Access the Web Interface**:
    Navigate to `http://localhost:3000` (or your server's IP).

2.  **Fill in App Details**:
    *   **App Name**: Enter a unique slug. This will be used to create a dedicated Git branch `app/<slug>`.
    *   **Expo Access Token**: Your Expo authentication token.
    *   **Source Repo**: (Optional) URL of a Template repository to clone. If left blank, a default "Blank" template is used.

3.  **Configure Credentials**:
    *   **Android**: Upload/path to Keystore (or let it auto-generate one).
    *   **iOS**: Provide P12 Certificate and Provisioning Profile paths.

4.  **Start Build**:
    *   Click **Create & Build App**.
    *   **Live Logs**: You will see real-time logs streaming from the server as it:
        *   Clones/Scaffolds the app.
        *   Configures `app.json`.
        *   Runs `eas build`.

5.  **Artifacts**:
    *   Once the build completes, a direct download link (Expo Artifact URL) will be provided.

---

## 🏗️ Architecture & Internal Workflow

This branch uses a **Direct Server Execution** model.

### High-Level Flow

```mermaid
graph TD
    User[User @ Web UI] -->|Submits Form| API[Next.js API Route]
    API -->|Instantiates| Framework[MyFramework Class]
    
    subgraph Server Context
        Framework -->|1. Scaffolds| AppDir[Temp App Directory]
        Framework -->|2. Injects| Config[app.json / eas.json]
        Framework -->|3. Git Ops| Git[Push to Branch app/xyz]
        Framework -->|4. Executes| EAS[EAS CLI Process]
    end
    
    EAS -->|Builds| Cloud[Expo Cloud Builders]
    EAS -->|Submits| Apple[TestFlight]
    
    EAS -.->|Streams Logs| API
    API -.->|SSE Stream| User
```

### Key Components (`src/lib/framework.ts`)

1.  **`MyFramework` Class**:
    The core orchestrator that manages the lifecycle of an automated build.

2.  **App Generation Strategy**:
    *   **Branch Reuse**: Checks if a branch `app/<appName>` already exists in the *hosting* repo. If so, it reuses it.
    *   **Template Cloning**: If `repoUrl` is provided, it clones that repo.
    *   **Scaffolding**: If neither, it runs `npx create-expo-app` to generate a fresh blank app.

3.  **Git Management**:
    *   The tool runs inside a Git repository.
    *   For every new app build, it creates an **Orphan Branch** (`app/<appName>`).
    *   It commits the generated code and pushes it to `origin`. This ensures every build has a reproducible source history.

4.  **Local Execution**:
    *   Instead of dispatching to GitHub Actions, this tool uses Node.js `spawn` and `execSync` to run `eas build` commands **locally on the server**.
    *   **Benefit**: Immediate feedback, no external CI dependencies.
    *   **Requirement**: The server must be capable of running Node.js processes for extended periods.

---

## 💻 Prerequisites & Setup

Since this runs builds locally, your server environment must be prepared.

### System Requirements
*   **OS**: Linux (Ubuntu/Debian recommended), macOS, or Windows using WSL.
*   **Runtime**: Node.js 18+.
*   **Git**: Installed and authenticated (SSH keys or HTTPS credentials stored).

### Installation

1.  **Clone the Repo**:
    ```bash
    git clone https://github.com/YourRepo/Expo-Automation.git
    cd Expo-Automation
    ```

2.  **Install Dependencies**:
    ```bash
    npm install
    ```

3.  **Install Global Tools**:
    The framework relies on `eas-cli`.
    ```bash
    npm install -g eas-cli
    ```

4.  **Environment Variables**:
    Create a `.env.local` file:
    ```bash
    EXPO_TOKEN=your_token_here (Optional default)
    ```

### Running the Server

```bash
# Development
npm run dev

# Production
npm run build
npm start
```

---

## 🔑 Credentials Handling

*   **Transient**: Credentials used during the build are written to `credentials.json` in a temporary directory.
*   **Cleanup**: The temporary directory is deleted after the build completes (success or fail).
*   **Security**: Ensure your server is secure, as credentials exist on the filesystem for the duration of the build.

---

> _Built with ❤️ for the Expo Community._