Metadata-Version: 2.4
Name: flutter-dev
Version: 0.1.6
Summary: A cross-platform CLI toolkit for Flutter development workflows.
Author: Royal Court BD
License-Expression: MIT
Project-URL: Homepage, https://github.com/royalcourtbd/flutter-development-tools
Project-URL: Repository, https://github.com/royalcourtbd/flutter-development-tools
Project-URL: Issues, https://github.com/royalcourtbd/flutter-development-tools/issues
Project-URL: Changelog, https://github.com/royalcourtbd/flutter-development-tools/blob/main/CHANGELOG.md
Keywords: flutter,cli,developer-tools,automation
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-dotenv>=0.19.0
Requires-Dist: requests>=2.25.0
Dynamic: license-file

# Flutter Dev

`flutter-dev` is a cross-platform Python CLI toolkit for automating common Flutter development workflows. It exposes the `fdev` command for project setup, release builds, device utilities, Git automation, AI-generated commit messages, screen mirroring, Firebase web deployment, and small productivity tools around an existing Flutter project.

The package is published on PyPI as `flutter-dev` and installs console commands for day-to-day Flutter work:

```bash
python -m pip install flutter-dev
```

Current package metadata declares version `0.1.6`, Python `>=3.8`, MIT license, and support for macOS, Linux, and Windows.

## Key Features

- Flutter build automation for APK, split APK, AAB, IPA, release install, and Firebase web deploy.
- Project maintenance helpers for `flutter clean`, dependency refresh, `build_runner`, localization generation, analysis, formatting, cache repair, and CocoaPods.
- Localization CSV helpers for exporting ARB files to translator-friendly CSV files and generating ARB files back from CSV.
- Android device helpers for APK install, app uninstall, foreground app data clearing, screen mirroring with `scrcpy`, wireless ADB setup, and Date & Time settings.
- AI-assisted Git commits using Groq, Mistral, SambaNova, or OpenRouter-compatible chat completion APIs.
- Git workflow helpers for version tags, branch sync, deployment branch merge, discard, and GitHub account management through `gh`.
- Feature/page generator that creates a `lib/features/<name>` structure using the project's presenter/base-state pattern.
- Small Tkinter desktop dashboard opened by running `fdev` with no command, with live colored command logs.
- Environment diagnostics through `fdev doctor`.
- Small utilities for Homebrew cleanup, file merging from `paths.txt`, AI provider switching, PyPI self-upgrade/delete, and git diff prompt export.

## Installation

### Install From PyPI

```bash
python -m pip install flutter-dev
```

Verify the CLI is available:

```bash
fdev doctor
```

`python -m pip install flutter-dev` installs the Python package, Python dependencies, and console scripts into the Python environment selected by `python`. It does not install Flutter, Dart, Git, Android SDK tools, CocoaPods, Firebase CLI, GitHub CLI, `scrcpy`, Java/JDK, or VS Code CLI.

The desktop dashboard uses Python Tkinter. Some Python distributions install this separately; for Homebrew Python, install the matching package such as `brew install python-tk@3.14`.

### Install From Source

```bash
git clone https://github.com/royalcourtbd/flutter-development-tools.git
cd flutter-development-tools
python -m pip install .
```

For editable local development:

```bash
python -m pip install -e .
```

### Legacy Installer

The repository still includes `install_legacy.py` for the older `~/scripts/flutter-tools` and `~/bin` style installation:

```bash
python install_legacy.py
```

For new PyPI-based installs, prefer the console scripts installed by `pip`.

## Requirements

Core requirements checked by `fdev doctor`:

- Python 3.8 or newer
- Flutter SDK
- Dart SDK
- Git
- Python packages: `python-dotenv`, `requests`

Feature-specific external tools:

| Tool | Used by |
| --- | --- |
| Android SDK Platform Tools / `adb` | `install`, `uninstall`, `clear-data`, `mirror`, `datetime`, `release-run` |
| Java/JDK | Android builds |
| CocoaPods | `pod`, `ipa` |
| Xcode / `xcrun` | iOS simulator and IPA workflows on macOS |
| `scrcpy` | `mirror` |
| Firebase CLI | `web-deploy` |
| GitHub CLI / `gh` | `fdev git ...` |
| VS Code CLI / `code` | Conflict helper in branch sync |
| Homebrew | `brew`, macOS `install-scrcpy` flow |
| Python Tkinter | Desktop dashboard opened by `fdev` |

## Quick Start

Run commands from the root of a Flutter project when they need `pubspec.yaml`, Android Gradle files, iOS files, or build outputs.

```bash
# Open the desktop dashboard
fdev

# Show command help
fdev help

# Upgrade the fdev CLI from PyPI
fdev upgrade

# Check environment and optional tools
fdev doctor

# Generate localization files
fdev lang

# Export ARB translations from lib/l10n to translations.csv
fdev arb-to-csv

# Generate ARB files in lib/l10n from translations.csv
fdev csv-to-arb

# Run build_runner
fdev db

# Build a release APK
fdev apk

# Build and install a release APK on a connected Android device
fdev release-run

# Mirror an Android device
fdev mirror

# Generate an AI-assisted commit message and commit after confirmation
fdev commit
```

## Command Reference

### Build Commands

| Command | Description |
| --- | --- |
| `fdev apk` | Runs clean, pub get, `flutter gen-l10n`, `build_runner`, then `flutter build apk --release --obfuscate --target-platform android-arm64 --split-debug-info=./`. |
| `fdev apk-split` | Builds release APKs with `--split-per-abi`. |
| `fdev aab` | Builds a release Android App Bundle with obfuscation and split debug info. |
| `fdev ipa` | Builds an App Store IPA on non-Windows systems; runs CocoaPods steps when `ios/` exists. |
| `fdev release-run` | Builds a release APK, installs it on a selected Android device, and launches the app. |
| `fdev web-deploy` | Runs `flutter build web --release`, then `firebase deploy --only functions,hosting`. |

Android APK/AAB build commands rename output files using the Android app label and current date (`DD_MMM`) when the label is available, display file sizes, and open the output directory.

### Project Commands

| Command | Description |
| --- | --- |
| `fdev setup` | Runs clean, dependency upgrade, `build_runner`, localization generation, another dependency upgrade, `flutter analyze`, and `dart format .`. |
| `fdev cleanup` | Runs clean, pub get, `dart fix --apply`, `dart format .`, and `flutter pub upgrade --major-versions`. |
| `fdev lang` | Runs `flutter gen-l10n`. |
| `fdev arb-to-csv` | Exports `lib/l10n/*.arb` into `translations.csv` by default. Use `-d/--directory` and `-o/--output` to override paths. |
| `fdev csv-to-arb` | Generates `app_<locale>.arb` files into `lib/l10n` from `translations.csv` by default. Use `-i/--input` and `-o/--output-dir` to override paths. |
| `fdev db` | Runs `dart run build_runner build --delete-conflicting-outputs`. |
| `fdev cache-repair` | Runs `flutter pub cache repair`. |
| `fdev pod` | Updates CocoaPods from the `ios/` directory after removing `Podfile.lock` when present. |
| `create-page page <page_name>` | Generates a feature/page structure directly through the packaged console script. |
| `fdev page <page_name>` | Legacy wrapper that currently calls `~/scripts/flutter-tools/create_page.py`; for PyPI installs, prefer `create-page page <page_name>`. |

### Device Commands

| Command | Description |
| --- | --- |
| `fdev install` | Installs a built APK from `build/app/outputs/flutter-apk`, prefers `arm64-v8a`, retries after uninstall on failure, then launches the app. |
| `fdev uninstall` | In a Flutter project root, uninstalls by package/bundle id. Outside a project, detects the foreground app and asks for confirmation. |
| `fdev clear-data` | Detects the foreground app, asks for confirmation, and runs `adb shell pm clear <package>` on Android. iOS prints manual options. |
| `fdev install-scrcpy` | Installs `scrcpy` using the best supported package manager for the current platform. |
| `fdev mirror` | Launches `scrcpy` for a selected Android device. |
| `fdev mirror --wireless` | Guides wireless ADB setup using a USB-connected Android device. |
| `fdev mirror --no-top` | Launches `scrcpy` without the always-on-top flag. |
| `fdev datetime` | Disables Android auto-time and opens Date & Time settings on the selected device. |

When multiple Android devices are connected, device-aware commands prompt you to choose a device.

### Git Commands

| Command | Description |
| --- | --- |
| `fdev commit` | Generates a Conventional Commit-style message from `git diff HEAD`, asks for confirmation, stages unstaged changes with `git add .`, then commits. |
| `fdev tag` | Auto-increments the latest Git tag, updates `pubspec.yaml` version/build number, commits the version bump, creates the tag, and pushes the commit and tag. |
| `fdev discard` | Prompts, then discards tracked changes and removes untracked files using Git commands. |
| `fdev sync <branch...>` | Fetches, merges named branches into the current branch, pushes, then merges current branch back into those branches. Requires a clean worktree. |
| `fdev deploy` | Merges the current branch into `deployment` and pushes it. Requires a clean worktree. |
| `fdev git` | Opens an interactive GitHub account manager using the GitHub CLI. |

`fdev git` subcommands:

```bash
fdev git status
fdev git list
fdev git switch <username>
fdev git add
fdev git remove <username>
fdev git config
```

Switching GitHub accounts runs `gh auth switch` and `gh auth setup-git`, but it does not automatically change `git user.name` or `git user.email`. Use `fdev git config` when you want to update Git identity.

### Utility Commands

| Command | Description |
| --- | --- |
| `fdev` | Opens a small Tkinter desktop dashboard for running `fdev` commands with live colored logs and command input. The terminal process stays running while the window is open. |
| `fdev help` | Shows command help without opening the dashboard. |
| `fdev doctor` | Checks platform, Python, Flutter/Dart/Git, Python packages, Android/iOS tools, optional CLIs, `.env`, Flutter project detection, and global `fdev` availability. |
| `fdev upgrade` | Detects the OS, then upgrades the active Python environment's `flutter-dev` package from PyPI with `python -m pip install --upgrade flutter-dev`. |
| `fdev delete` | Detects the OS, asks for confirmation, then uninstalls the active Python environment's `flutter-dev` package. Use `fdev delete --yes` to skip confirmation. |
| `fdev ai` | Shows the current AI provider and opens an interactive provider switch prompt. |
| `fdev ai <provider>` | Switches `DEFAULT_AI_SERVICE` to `groq`, `mistral`, `sambanova`, or `openrouter`. |
| `fdev brew` | Interactive Homebrew package manager for viewing packages, uninstalling with cleanup, clearing cache, and global cleanup. |
| `fdev merge` | Reads paths from `paths.txt`, merges file contents into `path_merge_files.txt`, and opens the result when there are no failures. |
| `gemini-api` | Tests the currently selected AI provider configuration. |
| `git-diff-editor` | Writes `git diff` output plus a prompt into `diff_output.txt` and opens it with the default app. |

## AI Configuration

AI features are used by `fdev commit` and `gemini-api`. Despite the historical `gemini_api.py` filename, the current source supports these providers:

- `groq`
- `mistral`
- `sambanova`
- `openrouter`

Each provider expects an API key, API URL, and model name. A typical configuration looks like this:

```env
GROQ_API_KEY=your_groq_api_key_here
GROQ_API_URL=https://api.groq.com/openai/v1/chat/completions
GROQ_MODEL=llama-3.3-70b-versatile

MISTRAL_API_KEY=your_mistral_api_key_here
MISTRAL_API_URL=https://api.mistral.ai/v1/chat/completions
MISTRAL_MODEL=mistral-medium

SAMBANOVA_API_KEY=your_sambanova_api_key_here
SAMBANOVA_API_URL=https://api.sambanova.ai/v1/chat/completions
SAMBANOVA_MODEL=Meta-Llama-3.3-70B-Instruct

OPENROUTER_API_KEY=your_openrouter_api_key_here
OPENROUTER_API_URL=https://openrouter.ai/api/v1/chat/completions
OPENROUTER_MODEL=openai/gpt-3.5-turbo

DEFAULT_AI_SERVICE=groq
```

The AI runtime searches for configuration in this order:

1. `FLUTTER_DEV_ENV`
2. `$XDG_CONFIG_HOME/flutter-dev/.env`
3. `~/.config/flutter-dev/.env`
4. `~/scripts/flutter-tools/.env`
5. `.env` beside the installed module/source
6. `.env` in the current working directory

Recommended setup:

```bash
mkdir -p ~/.config/flutter-dev
nano ~/.config/flutter-dev/.env
```

Then test:

```bash
fdev ai
gemini-api
```

Note: the current `fdev doctor` `.env` check is more limited than the AI runtime lookup. If `doctor` reports a missing `.env` but `gemini-api` succeeds, the AI configuration is still usable.

## Feature/Page Generation

Use the packaged command:

```bash
create-page page user_profile
```

This reads the Flutter project name from `pubspec.yaml`, lowercases the page name, converts snake_case to PascalCase for class names, and creates:

```text
lib/features/user_profile/
  data/
    datasource/
    models/
    repositories/user_profile_repository_impl.dart
  domain/
    datasource/
    entities/
    repositories/user_profile_repository.dart
    usecase/
  presentation/
    presenter/user_profile_presenter.dart
    presenter/user_profile_ui_state.dart
    ui/user_profile_page.dart
    widgets/
  di/user_profile_di.dart
```

The generated Dart pattern is based on:

- `{Prefix}Repository`
- `{Prefix}RepositoryImpl`
- `{Prefix}Di`
- `{Prefix}Presenter extends BasePresenter<{Prefix}UiState>`
- `{Prefix}UiState extends BaseUiState`
- a simple `StatelessWidget` page

If `lib/core/di/service_locator.dart` exists, the generator attempts to add the feature DI import and `await {Prefix}Di.setup(_serviceLocator);` near `//Feature DI setup`.

Important notes:

- The generator overwrites the generated target files if they already exist.
- `service_locator.dart` updates are regex-based and skipped when the file is missing.
- The source does not generate BLoC/Cubit templates; it generates the project's presenter/base-state pattern.

## Architecture

The package is organized as a Python CLI with a thin dispatcher and feature-specific managers:

```text
fdev.py                 Main command dispatcher
create_page.py          Flutter feature/page generator
gemini_api.py           AI commit-message provider client and config loader
git_diff_output_editor.py
common_utils.py         Shared colors, spinners, env helpers, platform helpers
core/constants.py       Shared regex patterns, paths, and build command constants
core/state.py           Selected Android device state
managers/build.py       APK/AAB/IPA/release-run build workflow
managers/project.py     setup, cleanup, lang, db, pod, cache repair
managers/app.py         install, uninstall, foreground app data clearing
managers/device.py      ADB device detection and selection
managers/mirror.py      scrcpy install, mirror, wireless ADB setup
managers/git.py         commit, tag, discard, branch sync, deployment merge
managers/git_account.py GitHub account manager around gh CLI
managers/doctor.py      Environment diagnostics
managers/package.py     PyPI self-upgrade and local uninstall commands
managers/ai.py          AI provider status and switching
managers/brew.py        Interactive Homebrew manager
managers/merge.py       paths.txt to path_merge_files.txt merger
managers/web_deploy.py  Flutter web build plus Firebase deploy
managers/datetime.py    Android Date & Time settings helper
```

The installed Python layout is top-level modules plus the `core` and `managers` packages; it is not a single import package named `flutter_dev`.

## Important Behavior Notes

- Many `fdev` commands mutate your Flutter project, Git repository, connected device, or local tool environment. Read command output before confirming prompts.
- `fdev commit` can stage all unstaged changes before committing.
- `fdev tag` updates `pubspec.yaml`, creates a commit, creates a Git tag, and pushes both.
- `fdev discard` removes tracked changes and untracked files after confirmation.
- `fdev cleanup` applies `dart fix`, formats the project, and runs a major-version dependency upgrade.
- `fdev clear-data` clears app data on Android after confirmation.
- `fdev uninstall` may fall back to foreground app detection outside a Flutter project root.
- `fdev upgrade` and `fdev delete` manage the local `flutter-dev` Python package, not the Flutter app on a device.
- `fdev delete` removes the `fdev` command from the current Python environment after confirmation; reinstall with `python -m pip install flutter-dev`.
- `fdev` with no command opens the desktop dashboard. Use `fdev help` to print command usage.
- Most command subcommands create build output directories at startup in the current working directory.
- Some subcommands return failure internally without always mapping that failure to a non-zero process exit code, so automation should inspect command output carefully.

## Troubleshooting

### Command Not Found

Make sure the Python environment where you installed the package is active:

```bash
python -m pip show flutter-dev
python -m pip install --upgrade flutter-dev
```

Then check:

```bash
which fdev
fdev doctor
```

On Windows, use:

```powershell
where fdev
```

### Upgrade Or Remove fdev

Use the built-in package management commands from the Python environment where `fdev` is installed:

```bash
fdev upgrade
fdev delete
```

Both commands print the detected OS and exact Python executable before running. They use that executable with `-m pip`, not a hardcoded `python`, `python3`, `pip`, or `pip3`, so the active venv/global Python that launched `fdev` is the environment that gets upgraded or deleted. On Windows, `fdev delete` and `fdev upgrade` schedule the same `sys.executable -m pip ...` operation in a delayed command process so the currently running console launcher can exit first.

### Flutter Project Not Detected

Run project-specific commands from the directory that contains `pubspec.yaml`.

### Build Commands Fail

Check that Flutter, Dart, Android SDK tools, Java/JDK, and project dependencies are installed:

```bash
fdev doctor
flutter doctor
```

### AI Commit Fails

Check provider configuration and network access:

```bash
fdev ai
gemini-api
```

Ensure the selected provider has all three values set:

- `<PROVIDER>_API_KEY`
- `<PROVIDER>_API_URL`
- `<PROVIDER>_MODEL`

### Screen Mirroring Fails

Install or repair `scrcpy`:

```bash
fdev install-scrcpy
fdev mirror
```

For wireless mirroring, connect the device over USB first:

```bash
fdev mirror --wireless
```

### `create-page` Works But `fdev page` Fails

For PyPI installs, use:

```bash
create-page page <page_name>
```

The `fdev page` wrapper still targets the legacy `~/scripts/flutter-tools/create_page.py` path.

## Packaging And Release Checks

For local packaging checks:

```bash
python -m pip install --upgrade build twine
rm -rf dist build flutter_dev.egg-info
python -m build
python -m twine check dist/*
```

Keep secrets out of release artifacts and documentation. Do not commit `.env` files or API keys. Use placeholder values in examples.

## License

MIT License. See [LICENSE](LICENSE).

## Links

- Homepage: https://github.com/royalcourtbd/flutter-development-tools
- Repository: https://github.com/royalcourtbd/flutter-development-tools
- Issues: https://github.com/royalcourtbd/flutter-development-tools/issues
- Changelog: https://github.com/royalcourtbd/flutter-development-tools/blob/main/CHANGELOG.md
