Metadata-Version: 2.4
Name: flutter-dev
Version: 0.1.10
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.10`, 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.
- 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.

### 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 |

## 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
# Show command help
fdev

# Show command help
fdev help

# Upgrade the fdev CLI from PyPI
fdev upgrade

# Check environment and optional tools
fdev doctor

# Initialize persistent AI configuration
fdev init

# 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 and runs `adb shell pm clear <package>` on Android. Confirmation is skipped when it matches the current Flutter project; otherwise the default-Yes safety prompt is shown. 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 mirror --turn-screen-off` | Launches `scrcpy` while keeping the Android device display turned off. |
| `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` | Shows command help. |
| `fdev help` | Shows command help. |
| `fdev doctor` | Checks platform, Python, Flutter/Dart/Git, Python packages, Android/iOS tools, optional CLIs, `.env`, Flutter project detection, and global `fdev` availability. |
| `fdev init` | Creates or repairs the persistent AI `.env` with safe provider defaults and empty API keys. |
| `fdev upgrade` | Shows the current version, Python environment, package location, and PyPI source, then upgrades with `python -m pip install --upgrade flutter-dev` and reports the resulting version. |
| `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 ai <provider> <model>` | Switches provider when needed and saves a custom model ID for that provider. |
| `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-latest

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. `%APPDATA%/flutter-dev/.env` on Windows, otherwise `~/.config/flutter-dev/.env`
4. The legacy `~/.config/flutter-dev/.env` path on Windows
5. `~/scripts/flutter-tools/.env`

Recommended setup:

```bash
fdev init
```

`fdev init` never writes real credentials. It creates all provider URL/model
defaults with empty API-key fields, preserves existing values, and restricts the
file to the current user on Unix-like systems. On macOS and Linux the default
path is `~/.config/flutter-dev/.env`.

Then select a provider and test:

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

If the selected provider's key is missing, `fdev commit` or `gemini-api` asks
for it using hidden terminal input and saves it to the active configuration.
After a new key is entered, press Enter to use the displayed default model or
enter another model ID for the same provider. Exported environment variables
continue to take precedence over values stored in `.env`.

Pressing `Ctrl+C` during key/model setup cancels the operation without saving a
partial key or sending an AI request. If an exported variable conflicts with a
provider/model change, `fdev` reports the override and asks you to unset it
instead of claiming that the file change became active.

Change the model later without replacing the API key:

```bash
fdev ai groq llama-3.1-8b-instant
```

`fdev doctor`, `fdev ai`, `gemini-api`, and `fdev commit` use the same persistent
configuration lookup.

## 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` skips confirmation only when the foreground Android app matches the current Flutter project's package ID; otherwise it uses a default-Yes `[Y/n]` 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 upgrade` reports the installed version and location before upgrading, then shows the before→after version when the active process can verify it immediately.
- `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 prints 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
fdev mirror --turn-screen-off
```

`--turn-screen-off` may be combined with `--no-top`. The mirrored window stays
active, but the physical Android display is turned off on supported devices.

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
