Metadata-Version: 2.4
Name: fflow-cli
Version: 1.0.3
Summary: FlutterFlow Git workflow CLI — manage feature branches, exports, staging and pushes.
Author: Anupama K
License: MIT
Keywords: flutterflow,git,cli,workflow,flutter
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0.0
Requires-Dist: python-dotenv>=1.0.0

# fflow — FlutterFlow Git Workflow CLI

Automates the FlutterFlow → Git workflow for teams.  
Designed for developers who export FlutterFlow code via CLI and push to GitLab.

---

## Requirements

Before installing, make sure you have:

- **Python 3.9+** — [python.org/downloads](https://www.python.org/downloads/)

- **Git** — [git-scm.com](https://git-scm.com/)  
  Verify: `git --version`

- **Flutter SDK** (includes Dart) — [flutter.dev/docs/get-started/install](https://flutter.dev/docs/get-started/install)  
  Verify: `flutter --version`  
  Required to install the FlutterFlow CLI via `dart pub global`.

- **FlutterFlow CLI** — install via:
  ```bash
  dart pub global activate flutterflow_cli
  ```
  Add Dart's pub global bin to PATH if not already:
  ```bash
  # Mac/Linux (bash)
  echo 'export PATH="$PATH:$HOME/.pub-cache/bin"' >> ~/.bashrc && source ~/.bashrc

  # Mac (zsh)
  echo 'export PATH="$PATH:$HOME/.pub-cache/bin"' >> ~/.zshrc && source ~/.zshrc
  ```
  Verify: `flutterflow --version`

- **GitLab SSH access** — fflow pushes via SSH. Set up your SSH key:
  ```bash
  ssh-keygen -t ed25519 -C "your@email.com"
  cat ~/.ssh/id_ed25519.pub
  ```
  Copy the output and add it to GitLab under *Profile → SSH Keys*.  
  Verify: `ssh -T git@gitlab.com`

- **A GitLab repository** with your FlutterFlow project connected

- **A FlutterFlow export CLI command** — get it from your FlutterFlow project settings under *Developer Settings → Export Code CLI*

---

## Installation

### 1. Install pip (if not already installed)

**Mac / Linux:**
```bash
python3 -m ensurepip --upgrade
```
Or using the get-pip script:
```bash
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
python3 get-pip.py
```

**Windows:**
pip comes bundled with Python. If missing:
```powershell
python -m ensurepip --upgrade
```

Verify pip is installed:
```bash
pip3 --version
```

---

### 2. Add pip's bin directory to PATH

After installing pip packages, the `fflow` command needs to be on your PATH.

**Mac / Linux (bash):**
```bash
echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```

**Mac (zsh — default on macOS Catalina+):**
```bash
echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
```

**Windows:**  
Python's user scripts folder is usually `%APPDATA%\Python\PythonXX\Scripts`.  
Add it to PATH via *System Properties → Environment Variables → Path → Edit*.

Verify:
```bash
echo $PATH
```

---

### 3. Install fflow-cli

```bash
pip install fflow-cli
```

Verify the install:

```bash
fflow --help
```

---

## One-time Setup (per repository)

Run this inside your Flutter project's git repo:

```bash
cd /path/to/your/flutter/repo
fflow setup
```

You will be asked for:
1. **FlutterFlow CLI export command** — paste the full command from FlutterFlow (token stored securely, never in git)
2. **GitLab repository URL** — e.g. `git@gitlab.example.com:group/repo.git`
3. **Parent branches** — e.g. `uat`, `migrated_uat`, `migrated_prod`
4. **Custom files** — any hand-written files to protect from FF export overwrites

> Run `fflow setup` again anytime to update individual settings.

---

## Daily Usage

Every time you work — just run:

```bash
fflow
```

fflow reads your current git state and guides you through every step interactively:

1. Creates your feature branch (`PROJ-123-uat`)
2. Runs FlutterFlow CLI export
3. Restores your custom code files automatically
4. Asks which pages/folders you worked on
5. Shows exact file list before staging
6. Detects if someone pushed to the parent branch mid-work
7. Safely syncs (rebases) without losing your work
8. Commits with the correct format (`PROJ-123 LoginPage, ProfilePage changes`)
9. Pushes to GitLab

---

## Commands

| Command | When to use |
|---|---|
| `fflow` | Every time — runs the main workflow |
| `fflow setup` | Once per repo, or to update settings |
| `fflow doctor` | When something looks broken |
| `fflow status` | Check current task phase and branch |

---

## Branch & Commit Format

- **Branch:** `PROJ-123-uat`
- **Commit:** `PROJ-123 LoginPage, ProfilePage changes`

---

## Custom File Protection

Protect hand-written files that would otherwise be overwritten by FlutterFlow export:

```bash
fflow setup  # → choose "Custom files" to add/remove entries
```

Before every FF export, fflow backs up all registered files and restores them after — your code is never lost.

---

## Mid-Work Sync

If someone pushes to the parent branch while you're working, fflow:

1. Detects it automatically before every step
2. Warns you with the number of new commits
3. Stashes your changes → rebases → re-applies → restores custom files
4. Auto-resolves FF-generated file conflicts
5. Pauses for manual resolution on your files
6. Run `fflow` again after resolving to continue

---

## Files Created in Your Repo

| File | Purpose | Git-tracked? |
|---|---|---|
| `.fflow.json` | Project config (branches, endpoint, project ID) | ✔ Yes |
| `.fflow.env` | Your FF token (secret) | ✖ No (gitignored) |
| `.fflow_registry.json` | List of your custom files | ✔ Yes |
| `.fflow_state.json` | Current task session state | ✖ No (gitignored) |
| `.fflow_custom_backup/` | Backup of custom files before FF export | ✖ No (gitignored) |

---

## Upgrading

```bash
pip install --upgrade fflow-cli
```
