optikit 1.2.5 → 1.3.0

package/.history/README_20260325211923.md

@@ -0,0 +1,268 @@
+<h1 align="center">OptiKit CLI</h1>
+
+<p align="center">
+  <strong>The command-line toolkit for Flutter & Opticore developers.</strong><br/>
+  Build &middot; Version &middot; Clean &middot; Generate &middot; Ship
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/optikit"><img src="https://img.shields.io/npm/v/optikit?style=flat-square&color=cyan&label=npm" alt="npm"/></a>
+  <img src="https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=flat-square" alt="Platform"/>
+  <a href="https://pub.dev/packages/opticore"><img src="https://img.shields.io/badge/Opticore-pub.dev-teal?style=flat-square" alt="Opticore"/></a>
+  <a href="https://www.linkedin.com/in/dev-mahmoud-elshenawy/"><img src="https://img.shields.io/badge/Creator-Mahmoud%20El%20Shenawy-blue?style=flat-square" alt="Creator"/></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow?style=flat-square" alt="License"/></a>
+</p>
+
+<p align="center">
+  <a href="https://www.buymeacoffee.com/m.elshenawy">
+    <img src="https://img.shields.io/badge/Buy%20Me%20A%20Coffee-Support%20My%20Work-FFDD00?style=for-the-badge&logo=buymeacoffee&logoColor=0D1117" alt="Buy Me A Coffee"/>
+  </a>
+</p>
+
+---
+
+## Install
+
+```bash
+npm install -g optikit
+```
+
+Then add one alias to your shell:
+
+```bash
+echo 'alias ok="optikit"' >> ~/.zshrc && source ~/.zshrc
+```
+
+Now every command starts with `ok`.
+
+---
+
+## Quick Start
+
+```bash
+ok init                    # Setup OptiKit in your project
+ok v                       # Show current version
+ok bump patch              # 1.0.0 -> 1.0.1
+ok apk                     # Build release APK
+ok ipa --clean -o          # Clean, build IPA, open output
+ok tf                      # TestFlight: bump iOS + build IPA
+ok gen module login -r     # Generate BLoC module with route
+ok aliases                 # See all commands & shortcuts
+```
+
+---
+
+## Commands
+
+Every command has a **short alias**. Use whichever you prefer.
+
+### Build
+
+| Alias | Command | What it does |
+|-------|---------|-------------|
+| `ok apk` | `flutter-build-apk` | Build release APK |
+| `ok aab` | `flutter-build-bundle` | Build release AAB |
+| `ok ios` | `flutter-build-ios` | Build iOS app |
+| `ok ipa` | `flutter-build-ipa` | Build release IPA |
+| `ok tf` | `testflight` | Bump iOS build + build IPA |
+
+**Build flags** — combine freely:
+
+| Flag | Short | What it does |
+|------|-------|-------------|
+| `--clean` | | Clean before building |
+| `--open` | `-o` | Open output folder after build |
+| `--bump <type>` | `-b` | Bump version before build (major/minor/patch) |
+| `--bump-ios` | `-i` | Bump iOS build number before build (IPA only) |
+| `--disable-fvm` | `-f` | Use global Flutter SDK |
+
+```bash
+ok apk --clean             # Clean + build APK
+ok ipa -b patch -o         # Bump patch + build IPA + open
+ok ipa --clean -i -o       # Clean + bump iOS + build IPA + open
+ok tf -o                   # TestFlight + open output
+```
+
+### Clean
+
+| Alias | Command | What it does |
+|-------|---------|-------------|
+| `ok c` | `clean` | Clean Flutter project |
+| `ok cf` | `clean-flutter` | Clean Flutter (explicit) |
+| `ok ci` | `clean-ios` | Clean iOS / CocoaPods |
+
+```bash
+ok c -a                    # Clean Flutter + iOS (all)
+ok ci -c                   # Clean iOS + clear cache
+ok ci -u                   # Clean iOS + update repo
+ok ci -cu                  # Clean iOS + cache + repo update
+```
+
+### Version & Bump
+
+| Alias | Command | What it does |
+|-------|---------|-------------|
+| `ok v` | `version` | Show current version info |
+| `ok bump patch` | `bump patch` | Bump patch (1.0.0 -> 1.0.1) |
+| `ok bump minor` | `bump minor` | Bump minor (1.0.0 -> 1.1.0) |
+| `ok bump major` | `bump major` | Bump major (1.0.0 -> 2.0.0) |
+| `ok bi` | `bump-ios` | Bump iOS build number only |
+| `ok ba` | `bump-android` | Bump Android build number only |
+| `ok bb` | `bump-build` | Bump both build numbers |
+| `ok vset` | `flutter-update-version` | Set version manually |
+
+> Version bumps auto-backup files and update `pubspec.yaml` + iOS project files.
+> See [Version Management](docs/VERSION_MANAGEMENT.md) for the full strategy.
+
+### Generate
+
+| Alias | Command | What it does |
+|-------|---------|-------------|
+| `ok gen module <name>` | `generate module` | Scaffold BLoC module (bloc, event, state, screen, factory) |
+| `ok gen repo <name>` | `generate repo` | Generate repository file |
+| `ok route <name>` | `add-route` | Add route to `app_router.dart` |
+
+```bash
+ok gen module login -r     # Generate module + register route
+```
+
+### Run & Devices
+
+| Alias | Command | What it does |
+|-------|---------|-------------|
+| `ok run` | `run` | Run app on connected device |
+| `ok rs` | `run-select` | Interactive device picker |
+| `ok devs` | `devices` | List connected devices |
+
+```bash
+ok run -r                  # Run in release mode
+ok run -d <device-id>      # Run on specific device
+ok rs -r                   # Pick device + release mode
+```
+
+### Open
+
+| Alias | Command | What it does |
+|-------|---------|-------------|
+| `ok xcode` | `open-ios` | Open in Xcode |
+| `ok studio` | `open-android` | Open in Android Studio |
+| `ok open-ipa` | `open-ipa` | Open IPA output folder |
+| `ok open-apk` | `open-apk` | Open APK output folder |
+| `ok open-bundle` | `open-bundle` | Open AAB output folder |
+
+> Tip: Use `ok ipa -o` or `ok apk -o` to build and open in one step.
+
+### Config & Tools
+
+| Alias | Command | What it does |
+|-------|---------|-------------|
+| `ok init` | `init` | Initialize OptiKit config |
+| `ok init-app` | `init-app` | Scaffold Opticore app structure |
+| `ok vscode` | `setup-vscode` | Create VS Code Flutter settings |
+| `ok undo` | `rollback` | List/restore file backups |
+| `ok info` | `status` | Project status snapshot |
+| `ok dr` | `doctor` | Check environment health |
+| `ok up` | `upgrade` | Check for CLI updates |
+| `ok aliases` | `aliases` | Show all aliases & shortcuts |
+
+---
+
+## Common Workflows
+
+**Release an APK:**
+```bash
+ok bump patch && ok apk    # or: ok apk -b patch
+```
+
+**TestFlight upload:**
+```bash
+ok tf -o                   # Bump iOS + build IPA + open output
+```
+
+**Full clean rebuild (iOS):**
+```bash
+ok ipa --clean -o          # Clean + build IPA + open
+```
+
+**New module:**
+```bash
+ok gen module user_profile -r   # Generate + auto-route
+```
+
+**Check everything:**
+```bash
+ok info                    # Version, config, platforms
+ok dr                      # Environment health check
+```
+
+---
+
+## Configuration
+
+Initialize with `ok init`. This creates `.optikitrc.json`:
+
+```json
+{
+  "backupRetentionCount": 5,
+  "useFvmByDefault": true,
+  "autoBackup": true,
+  "verbose": false
+}
+```
+
+**FVM:** All Flutter commands use FVM by default. Disable per-command with `-f` or set `"useFvmByDefault": false` in config.
+
+**Backups:** Version files are backed up automatically before changes. Use `ok undo` to list and restore.
+
+---
+
+## Tab Completion
+
+```bash
+optikit completion >> ~/.zshrc
+source ~/.zshrc
+```
+
+Now press Tab to autocomplete commands and flags.
+
+---
+
+## Documentation
+
+| Doc | What it covers |
+|-----|---------------|
+| **[Command Reference](docs/USAGE.md)** | All commands with flags and examples |
+| **[Version Management](docs/VERSION_MANAGEMENT.md)** | Dual build number strategy, iOS/Android workflows |
+| **[Installation](docs/INSTALLATION.md)** | NPM, Homebrew, and source install |
+
+---
+
+## Built for Opticore
+
+OptiKit is the companion CLI for the **[Opticore](https://pub.dev/packages/opticore)** Flutter micro-framework. Module generation scaffolds the full BLoC pattern that Opticore expects.
+
+Not using Opticore? OptiKit's build, version, and clean commands work with **any Flutter project**.
+
+---
+
+## Created By
+
+<div align="center">
+
+### Built with love by [Mahmoud El Shenawy](https://github.com/dev-mahmoud-elshenawy)
+
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?logo=linkedin&logoColor=white&style=for-the-badge)](https://www.linkedin.com/in/dev-mahmoud-elshenawy)
+[![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white&style=for-the-badge)](https://github.com/dev-mahmoud-elshenawy)
+[![Medium](https://img.shields.io/badge/Medium-000000?logo=medium&logoColor=white&style=for-the-badge)](https://medium.com/@dev-mahmoud-elshenawy)
+
+</div>
+
+---
+
+## License
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](./LICENSE)
+
+**OptiKit** is open-source software released under the **[MIT License](./LICENSE)**.
+
+Free to use, modify, and distribute — in personal and commercial projects.

package/.history/README_20260325212116.md

@@ -0,0 +1,268 @@
+<h1 align="center">OptiKit CLI</h1>
+
+<p align="center">
+  <strong>The command-line toolkit for Flutter & Opticore developers.</strong><br/>
+  Build &middot; Version &middot; Clean &middot; Generate &middot; Ship
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/optikit"><img src="https://img.shields.io/npm/v/optikit?style=flat-square&color=cyan&label=npm" alt="npm"/></a>
+  <img src="https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=flat-square" alt="Platform"/>
+  <a href="https://pub.dev/packages/opticore"><img src="https://img.shields.io/badge/Opticore-pub.dev-teal?style=flat-square" alt="Opticore"/></a>
+  <a href="https://www.linkedin.com/in/dev-mahmoud-elshenawy/"><img src="https://img.shields.io/badge/Creator-Mahmoud%20El%20Shenawy-blue?style=flat-square" alt="Creator"/></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow?style=flat-square" alt="License"/></a>
+</p>
+
+<p align="center">
+  <a href="https://www.buymeacoffee.com/m.elshenawy">
+    <img src="https://img.shields.io/badge/Buy%20Me%20A%20Coffee-Support%20My%20Work-FFDD00?style=for-the-badge&logo=buymeacoffee&logoColor=0D1117" alt="Buy Me A Coffee"/>
+  </a>
+</p>
+
+---
+
+## Install
+
+```bash
+npm install -g optikit
+```
+
+Then add one alias to your shell:
+
+```bash
+echo 'alias ok="optikit"' >> ~/.zshrc && source ~/.zshrc
+```
+
+Now every command starts with `ok`.
+
+---
+
+## Quick Start
+
+```bash
+ok init                    # Setup OptiKit in your project
+ok v                       # Show current version
+ok bump patch              # 1.0.0 -> 1.0.1
+ok apk                     # Build release APK
+ok ipa --clean -o          # Clean, build IPA, open output
+ok tf                      # TestFlight: bump iOS + build IPA
+ok gen module login -r     # Generate BLoC module with route
+ok aliases                 # See all commands & shortcuts
+```
+
+---
+
+## Commands
+
+Every command has a **short alias**. Use whichever you prefer.
+
+### Build
+
+| Alias | Command | What it does |
+|-------|---------|-------------|
+| `ok apk` | `flutter-build-apk` | Build release APK |
+| `ok aab` | `flutter-build-bundle` | Build release AAB |
+| `ok ios` | `flutter-build-ios` | Build iOS app |
+| `ok ipa` | `flutter-build-ipa` | Build release IPA |
+| `ok tf` | `testflight` | Bump iOS build + build IPA |
+
+**Build flags** — combine freely:
+
+| Flag | Short | What it does |
+|------|-------|-------------|
+| `--clean` | | Clean before building |
+| `--open` | `-o` | Open output folder after build |
+| `--bump <type>` | `-b` | Bump version before build (major/minor/patch) |
+| `--bump-ios` | `-i` | Bump iOS build number before build (IPA only) |
+| `--disable-fvm` | `-f` | Use global Flutter SDK |
+
+```bash
+ok apk --clean             # Clean + build APK
+ok ipa -b patch -o         # Bump patch + build IPA + open
+ok ipa --clean -i -o       # Clean + bump iOS + build IPA + open
+ok tf -o                   # TestFlight + open output
+```
+
+### Clean
+
+| Alias | Command | What it does |
+|-------|---------|-------------|
+| `ok c` | `clean` | Clean Flutter project |
+| `ok cf` | `clean-flutter` | Clean Flutter (explicit) |
+| `ok ci` | `clean-ios` | Clean iOS / CocoaPods |
+
+```bash
+ok c -a                    # Clean Flutter + iOS (all)
+ok ci -c                   # Clean iOS + clear cache
+ok ci -u                   # Clean iOS + update repo
+ok ci -cu                  # Clean iOS + cache + repo update
+```
+
+### Version & Bump
+
+| Alias | Command | What it does |
+|-------|---------|-------------|
+| `ok v` | `version` | Show current version info |
+| `ok bump patch` | `bump patch` | Bump patch (1.0.0 -> 1.0.1) |
+| `ok bump minor` | `bump minor` | Bump minor (1.0.0 -> 1.1.0) |
+| `ok bump major` | `bump major` | Bump major (1.0.0 -> 2.0.0) |
+| `ok bi` | `bump-ios` | Bump iOS build number only |
+| `ok ba` | `bump-android` | Bump Android build number only |
+| `ok bb` | `bump-build` | Bump both build numbers |
+| `ok vset` | `flutter-update-version` | Set version manually |
+
+> Version bumps auto-backup files and update `pubspec.yaml` + iOS project files.
+> See [Version Management](docs/VERSION_MANAGEMENT.md) for the full strategy.
+
+### Generate
+
+| Alias | Command | What it does |
+|-------|---------|-------------|
+| `ok gen module <name>` | `generate module` | Scaffold BLoC module (bloc, event, state, screen, factory) |
+| `ok gen repo <name>` | `generate repo` | Generate repository file |
+| `ok route <name>` | `add-route` | Add route to `app_router.dart` |
+
+```bash
+ok gen module login -r     # Generate module + register route
+```
+
+### Run & Devices
+
+| Alias | Command | What it does |
+|-------|---------|-------------|
+| `ok run` | `run` | Run app on connected device |
+| `ok rs` | `run-select` | Interactive device picker |
+| `ok devs` | `devices` | List connected devices |
+
+```bash
+ok run -r                  # Run in release mode
+ok run -d <device-id>      # Run on specific device
+ok rs -r                   # Pick device + release mode
+```
+
+### Open
+
+| Alias | Command | What it does |
+|-------|---------|-------------|
+| `ok xcode` | `open-ios` | Open in Xcode |
+| `ok studio` | `open-android` | Open in Android Studio |
+| `ok open-ipa` | `open-ipa` | Open IPA output folder |
+| `ok open-apk` | `open-apk` | Open APK output folder |
+| `ok open-bundle` | `open-bundle` | Open AAB output folder |
+
+> Tip: Use `ok ipa -o` or `ok apk -o` to build and open in one step.
+
+### Config & Tools
+
+| Alias | Command | What it does |
+|-------|---------|-------------|
+| `ok init` | `init` | Initialize OptiKit config |
+| `ok init-app` | `init-app` | Scaffold Opticore app structure |
+| `ok vscode` | `setup-vscode` | Create VS Code Flutter settings |
+| `ok undo` | `rollback` | List/restore file backups |
+| `ok info` | `status` | Project status snapshot |
+| `ok dr` | `doctor` | Check environment health |
+| `ok up` | `upgrade` | Check for CLI updates |
+| `ok aliases` | `aliases` | Show all aliases & shortcuts |
+
+---
+
+## Common Workflows
+
+**Release an APK:**
+```bash
+ok bump patch && ok apk    # or: ok apk -b patch
+```
+
+**TestFlight upload:**
+```bash
+ok tf -o                   # Bump iOS + build IPA + open output
+```
+
+**Full clean rebuild (iOS):**
+```bash
+ok ipa --clean -o          # Clean + build IPA + open
+```
+
+**New module:**
+```bash
+ok gen module user_profile -r   # Generate + auto-route
+```
+
+**Check everything:**
+```bash
+ok info                    # Version, config, platforms
+ok dr                      # Environment health check
+```
+
+---
+
+## Configuration
+
+Initialize with `ok init`. This creates `.optikitrc.json`:
+
+```json
+{
+  "backupRetentionCount": 5,
+  "useFvmByDefault": true,
+  "autoBackup": true,
+  "verbose": false
+}
+```
+
+**FVM:** All Flutter commands use FVM by default. Disable per-command with `-f` or set `"useFvmByDefault": false` in config.
+
+**Backups:** Version files are backed up automatically before changes. Use `ok undo` to list and restore.
+
+---
+
+## Tab Completion
+
+```bash
+optikit completion >> ~/.zshrc
+source ~/.zshrc
+```
+
+Now press Tab to autocomplete commands and flags.
+
+---
+
+## Documentation
+
+| Doc | What it covers |
+|-----|---------------|
+| **[Command Reference](docs/USAGE.md)** | All commands with flags and examples |
+| **[Version Management](docs/VERSION_MANAGEMENT.md)** | Dual build number strategy, iOS/Android workflows |
+| **[Installation](docs/INSTALLATION.md)** | NPM, Homebrew, and source install |
+
+---
+
+## Built for Opticore
+
+OptiKit is the companion CLI for the **[Opticore](https://pub.dev/packages/opticore)** Flutter micro-framework. Module generation scaffolds the full BLoC pattern that Opticore expects.
+
+Not using Opticore? OptiKit's build, version, and clean commands work with **any Flutter project**.
+
+---
+
+## Created By
+
+<div align="center">
+
+### Built with ❤️ by [Mahmoud El Shenawy](https://github.com/dev-mahmoud-elshenawy)
+
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?logo=linkedin&logoColor=white&style=for-the-badge)](https://www.linkedin.com/in/dev-mahmoud-elshenawy)
+[![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white&style=for-the-badge)](https://github.com/dev-mahmoud-elshenawy)
+[![Medium](https://img.shields.io/badge/Medium-000000?logo=medium&logoColor=white&style=for-the-badge)](https://medium.com/@dev-mahmoud-elshenawy)
+
+</div>
+
+---
+
+## License
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](./LICENSE)
+
+**OptiKit** is open-source software released under the **[MIT License](./LICENSE)**.
+
+Free to use, modify, and distribute — in personal and commercial projects.