optikit 1.2.4 → 1.3.0

package/.history/README_20260325222247.md

@@ -0,0 +1,328 @@
+<h1 align="center">🚀 OptiKit CLI</h1>
+
+<p align="center">
+  <strong>Build, version, and deploy Flutter apps in one CLI.</strong><br/>
+  The command-line toolkit for Flutter & Opticore developers.
+</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>
+  <a href="https://flutter.dev"><img src="https://img.shields.io/badge/Flutter-Compatible-02569B?style=flat-square&logo=flutter&logoColor=white" alt="Flutter"/></a>
+  <img src="https://img.shields.io/badge/MCP-Supported-orange?style=flat-square" alt="MCP Supported"/>
+  <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 & Go
+
+```bash
+npm install -g optikit
+```
+
+You get two commands — `optikit` (full name) and `ok` (shorthand). Both work identically.
+
+```bash
+optikit init                    # 🔧 Setup OptiKit in your project
+optikit bump patch              # 📦 1.0.0 → 1.0.1
+optikit apk                     # 🏗️ Build release APK
+optikit tf -o                   # 🚀 TestFlight: bump iOS + build IPA + open
+optikit gen module login -r     # 🧩 Generate BLoC module with route
+optikit aliases                 # 📋 See all shortcuts
+```
+
+> 💡 Prefer shorter commands? Use `ok` instead of `optikit` — every example above works with both.
+
+---
+
+## 🔥 Why OptiKit?
+
+| Feature | Description |
+|---------|-------------|
+| 🤖 **Claude Code Plugin** | AI understands your project and acts on it via MCP |
+| ✅ **Short aliases** | Every command has a memorable shortcut |
+| ✅ **Combo flags** | Clean, bump, build, and open in one command |
+| ✅ **Smart versioning** | Dual iOS/Android build numbers handled automatically |
+| ✅ **Auto backups** | Version files backed up before every change |
+| ✅ **Module scaffolding** | Full BLoC pattern generated in one command |
+| ✅ **FVM support** | Built-in Flutter Version Manager integration |
+
+---
+
+## 📖 Commands at a Glance
+
+> Every command has a short alias. Run `optikit aliases` to see the full list in your terminal.
+
+### 🏗️ Build
+
+| Command | Alias | What it does |
+|---------|-------|-------------|
+| `optikit flutter-build-apk` | `apk` | Build release APK |
+| `optikit flutter-build-bundle` | `aab` | Build release AAB |
+| `optikit flutter-build-ios` | `ios` | Build iOS app |
+| `optikit flutter-build-ipa` | `ipa` | Build release IPA |
+| `optikit testflight` | `tf` | Bump iOS build + build IPA |
+
+**Combo flags** — mix and match on any build command:
+
+```bash
+optikit apk --clean             # 🧹 Clean → build
+optikit ipa -b patch -o         # 📦 Bump → build → open output
+optikit ipa --clean -i -o       # 🧹 Clean → bump iOS → build → open
+optikit tf -o                   # 🚀 TestFlight → open output
+```
+
+### 🧹 Clean
+
+| Command | Alias | What it does |
+|---------|-------|-------------|
+| `optikit clean` | `c` | Clean Flutter project |
+| `optikit clean-flutter` | `cf` | Clean Flutter (explicit) |
+| `optikit clean-ios` | `ci` | Clean iOS / CocoaPods |
+
+```bash
+optikit clean -a                # Clean all (Flutter + iOS)
+optikit ci -cu                  # Clean iOS + cache + repo update
+```
+
+### 📦 Version
+
+| Command | Alias | What it does |
+|---------|-------|-------------|
+| `optikit version` | `v` | Show current version |
+| `optikit bump patch` | | Bug fix: 1.0.0 → 1.0.1 |
+| `optikit bump minor` | | Feature: 1.0.0 → 1.1.0 |
+| `optikit bump major` | | Breaking: 1.0.0 → 2.0.0 |
+| `optikit bump-ios` | `bi` | Bump iOS build only |
+| `optikit bump-android` | `ba` | Bump Android build only |
+| `optikit bump-build` | `bb` | Bump both build numbers |
+
+> 📘 Deep dive: **[Version Management](docs/VERSION_MANAGEMENT.md)**
+
+### 🧩 Generate
+
+```bash
+optikit gen module login        # Scaffold BLoC module
+optikit gen module login -r     # Scaffold + register route
+optikit gen repo user           # Generate repository
+optikit route settings          # Add route to app_router.dart
+```
+
+### 📱 Run & Open
+
+```bash
+optikit run                     # Run app on device
+optikit rs                      # Interactive device picker
+optikit devs                    # List connected devices
+optikit xcode                   # Open in Xcode
+optikit studio                  # Open in Android Studio
+```
+
+### 🔧 Tools
+
+```bash
+optikit info                    # Project status snapshot
+optikit dr                      # Environment health check
+optikit undo                    # List/restore backups
+optikit up                      # Check for CLI updates
+optikit vscode                  # Setup VS Code settings
+```
+
+---
+
+## 🎯 Common Workflows
+
+```bash
+# 🚀 TestFlight upload
+optikit tf -o
+
+# 📦 Release APK with version bump
+optikit apk -b patch -o
+
+# 🧹 Full clean rebuild
+optikit ipa --clean -o
+
+# 🧩 New feature module
+optikit gen module user_profile -r
+
+# 🔍 Check project state
+optikit info
+```
+
+---
+
+## ⚙️ Configuration
+
+```bash
+optikit init                    # Creates .optikitrc.json
+```
+
+```json
+{
+  "backupRetentionCount": 5,
+  "useFvmByDefault": true,
+  "autoBackup": true
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `backupRetentionCount` | `5` | Number of backups to keep per file |
+| `useFvmByDefault` | `true` | Use FVM for all Flutter commands |
+| `autoBackup` | `true` | Backup files before version changes |
+
+---
+
+## 💾 Backups & Rollback
+
+OptiKit **automatically backs up** version files before any modification:
+
+| File | Backed up before |
+|------|-----------------|
+| `pubspec.yaml` | Version bumps, clean |
+| `ios/Runner.xcodeproj/project.pbxproj` | Version bumps |
+| `ios/Runner/Info.plist` | Version bumps |
+
+Backups are stored in `.optikit-backup/` directories next to the original files with timestamps:
+
+```
+your-project/
+├── pubspec.yaml
+├── .optikit-backup/
+│   ├── pubspec_2026-03-25T10-30-00-000Z.yaml
+│   └── pubspec_2026-03-25T11-15-30-000Z.yaml
+└── ios/Runner.xcodeproj/
+    ├── project.pbxproj
+    └── .optikit-backup/
+        └── project_2026-03-25T10-30-00-000Z.pbxproj
+```
+
+**Manage backups:**
+
+```bash
+optikit undo                    # 📋 List all backups
+optikit undo --restore 1        # ♻️ Restore backup #1
+optikit undo --before 2026-03-20  # 📅 Filter backups by date
+```
+
+Old backups are automatically cleaned up (keeps last 5 by default, configurable via `backupRetentionCount`).
+
+> 💡 `.optikit-backup/` is added to `.gitignore` during `optikit init`.
+
+---
+
+## 🤖 AI-Powered with Claude Code
+
+<p align="center">
+  <a href="https://github.com/dev-mahmoud-elshenawy/optikit"><img src="https://img.shields.io/badge/Claude%20Code-Plugin-blueviolet?style=for-the-badge" alt="Claude Code Plugin"/></a>
+  <img src="https://img.shields.io/badge/MCP-Supported-orange?style=for-the-badge" alt="MCP Supported"/>
+  <img src="https://img.shields.io/badge/Transport-stdio-green?style=for-the-badge" alt="stdio Transport"/>
+</p>
+
+OptiKit ships as a **Claude Code plugin** powered by the **Model Context Protocol (MCP)**. Claude doesn't just run commands — it **understands your Flutter project** and makes intelligent decisions.
+
+### 🧠 How It Works
+
+You describe what you need. Claude **picks the right tools automatically**:
+
+| You say | Claude does |
+|---------|-----------|
+| *"Fix this build error"* | Runs `clean` → `build` automatically |
+| *"Prepare a TestFlight build"* | Runs `testflight` (bump iOS + build IPA) |
+| *"Create a login feature"* | Generates BLoC module + registers route |
+| *"We need to release v2.0"* | Bumps major version + builds both platforms |
+| *"What version are we on?"* | Shows version with iOS & Android build numbers |
+| *"Undo the last version bump"* | Lists backups and restores the right one |
+
+### ⚡ Setup in Seconds
+
+**Option 1 — Plugin Marketplace:**
+```bash
+/plugin marketplace add dev-mahmoud-elshenawy/optikit
+/plugin install optikit
+```
+
+**Option 2 — One Command:**
+```bash
+optikit setup-claude
+```
+
+That's it. All OptiKit tools are instantly available to Claude.
+
+### 🛠️ Available Tool Categories
+
+| Category | What Claude can do |
+|----------|--------------------|
+| 🏗️ **Build** | Build APK, AAB, iOS, IPA with clean/bump/open combos |
+| 🧹 **Clean** | Fix stale caches, CocoaPods issues, full project cleanup |
+| 📦 **Version** | Bump versions, manage iOS/Android build numbers independently |
+| 🧩 **Generate** | Scaffold BLoC modules, repositories, and auto-register routes |
+| 📱 **Run** | Launch app on devices, list connected devices |
+| 🔧 **Diagnostics** | Health checks, project status, backup management |
+| ⚙️ **Config** | Project setup, VS Code config, upgrade checks |
+
+The MCP server runs locally via stdio — fast, private, no cloud dependency.
+
+```bash
+optikit setup-claude              # ✅ Register with Claude Code
+optikit setup-claude --uninstall  # ❌ Remove when needed
+```
+
+---
+
+## 📘 Documentation
+
+| Doc | Description |
+|-----|-------------|
+| 📖 **[Command Reference](docs/USAGE.md)** | All commands, flags, and examples |
+| 📦 **[Version Management](docs/VERSION_MANAGEMENT.md)** | iOS/Android dual build strategy |
+| 🔧 **[Installation Guide](docs/INSTALLATION.md)** | NPM, Homebrew, source install |
+| 🔍 **[Troubleshooting](docs/TROUBLESHOOT.md)** | Common issues and quick fixes |
+
+---
+
+## ⚡ Supercharge Development with Opticore
+
+**OptiKit CLI** is the companion tool for **[Opticore](https://pub.dev/packages/opticore)** — a lightweight BLoC-based micro-framework for Flutter.
+
+| Together they give you | |
+|---|---|
+| 🧩 **Module scaffolding** | Generate full BLoC modules that plug directly into Opticore |
+| 🛣️ **Auto-routing** | Register routes in `app_router.dart` with one flag |
+| 🏗️ **App initialization** | Scaffold `main.dart`, config, and router for Opticore projects |
+| 📦 **Smart builds** | Build, version, and clean with short commands and combo flags |
+
+> 💡 **Not using Opticore?** No problem — build, version, clean, and run commands work with **any Flutter project**.
+
+📦 **[OptiKit on NPM](https://www.npmjs.com/package/optikit)** | 🔗 **[GitHub](https://github.com/dev-mahmoud-elshenawy/optikit)** | 🔗 **[Opticore on pub.dev](https://pub.dev/packages/opticore)**
+
+---
+
+## 👤 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 under the **[MIT License](./LICENSE)**. Free for personal and commercial use.

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "optikit": {
+      "command": "optikit",
+      "args": ["mcp"]
+    }
+  }
+}

package/CHANGELOG.md

@@ -1,69 +1,102 @@
-# Changelog
+# 📌 Changelog
 
-All notable changes to this project are documented in this file. Each release includes details about new features, improvements, bug fixes, and any breaking changes. This changelog helps users and developers track the evolution of the project and understand how different versions may impact their use of the tool.
+All notable changes to **OptiKit CLI** are documented here.
 
-We follow Semantic Versioning (SemVer) to indicate the nature of changes:
+## 🔄 Versioning Strategy
 
-	•	MAJOR: Breaking changes that may affect compatibility.
-	•	MINOR: New features or improvements that are backward compatible.
-	•	PATCH: Bug fixes and minor improvements that are backward compatible.
+We follow **Semantic Versioning (SemVer)**:
 
-Each section lists the changes in chronological order, with the most recent release at the top. We also include links to relevant discussions or issues when appropriate.
+- 🚀 **MAJOR**: Breaking changes that may affect compatibility
+- 🌟 **MINOR**: New features or improvements (backward compatible)
+- 🛠 **PATCH**: Bug fixes and minor improvements
 
-## [1.2.1]
+---
 
-### Added
+### 🌟 [1.3.0] - MCP Plugin, Short Aliases & Combo Flags
 
-- **Open Build Output Commands:** New commands to quickly access build artifacts:
-  - `open-ipa` - Opens the IPA build output directory (`build/ios/ipa/`)
-  - `open-apk` - Opens the APK build output directory (`build/app/outputs/flutter-apk/`)
-  - `open-bundle` - Opens the Android Bundle output directory (`build/app/outputs/bundle/release/`)
-- **Cross-Platform Support:** All open commands work seamlessly on macOS (Finder), Windows (Explorer), and Linux (default file manager)
-- **Smart Validation:** Commands check if build output exists before attempting to open, with helpful error messages
+- 🤖 **Claude Code Integration**:
+  - Built-in MCP server with 28 tools — Claude understands your Flutter project and acts on it
+  - `optikit mcp` starts the MCP server (stdio transport)
+  - `optikit setup-claude` registers the plugin with Claude Code (macOS, Linux, Windows)
+  - `optikit setup-claude --uninstall` removes the plugin cleanly
+  - Available as a Claude Code plugin via marketplace
 
-### Improved
+- 🆕 **New Features**:
+  - `ok` binary — use `ok` or `optikit` interchangeably, no shell alias needed
+  - 23 short aliases for all commands (`apk`, `ipa`, `tf`, `ci`, `bi`, `v`, `gen`, `rs`, `info`, `dr`, `undo`, `up`, and more)
+  - Combo build flags — `--clean`, `-o` (open), `-b` (bump), `-i` (bump-ios) on all build commands
+  - `testflight` / `tf` command — bump iOS build + build IPA in one step
+  - `aliases` command — full reference of all shortcuts, flags, and examples
+  - Short flags across commands — `-f`, `-a`, `-c`, `-u`, `-r`, `-i`
+  - Elapsed time display on build commands
+  - Tab completion via `optikit completion`
 
-- **Documentation:** Updated USAGE.md with comprehensive open build output commands section
-- **User Experience:** No need for shell aliases to access build outputs - built directly into the CLI
+- 🏗️ **Improvements**:
+  - CLI modularized into domain-specific command files
+  - Enhanced `--help` with grouped aliases and combo examples
+  - Branded startup banner with version display
+  - Logger upgraded with icons (✔ ✖ ⚠ ℹ) and new `step()` / `dim()` methods
 
-## [1.2.0]
+- 📝 **Documentation**:
+  - README, USAGE, VERSION_MANAGEMENT, INSTALLATION rewritten
+  - New TROUBLESHOOT.md for common issues
+  - Removed 4 redundant internal docs
 
-### Added
+- 🔄 **Changes**:
+  - `clean` alias changed from `ca` to `c`
+  - `flavor` flag on `run`/`run-select` no longer uses `-f` (conflicts with `--disable-fvm`)
 
-- **Device Management Commands:** New comprehensive device management system for Flutter development:
-  - `devices` - List all connected devices with numbered display, showing device names, platforms, IDs, and types (Physical/Emulator)
-  - `run` - Run Flutter app on a specific device with support for `--device`, `--release`, `--flavor`, and FVM options
-  - `run-select` - Interactive device selection with numbered prompts for easy device targeting
-- **Enhanced Architecture:** Reorganized codebase with domain-based folder structure for better maintainability:
-  - Commands organized by domain (build, clean, version, project, config)
-  - Utilities categorized into validators, helpers, and services
-  - Improved import paths and module organization
+### ⚡ [1.2.5] - Simultaneous Build Bump
 
-### Improved
+- Added `bump-build` command — increment both Android and iOS build numbers at once
 
-- **Documentation:** Updated README.md with streamlined feature list and better documentation links
-- **Code Quality:** Enhanced TypeScript type safety and error handling across device management features
+### 🎯 [1.2.4] - iOS Build Number Accuracy
 
-## [1.1.1]
+- Fixed `bump-ios` to read actual iOS build number from `project.pbxproj`
+- `version` command now shows Android and iOS build numbers separately
 
-### Added
+### 🧹 [1.2.3] - Silent Validation
 
-- **VS Code Setup Command:** Use the `setup-vscode` command to automatically create a `.vscode` folder with recommended Flutter settings—configured specifically for FVM. This command streamlines your project setup by setting the Flutter SDK path to `.fvm/flutter_sdk`, ensuring a smooth development experience for FVM users.
+- Removed unwanted version output during command validation
 
-## [1.0.4]
+### 🔧 [1.2.2] - Command Naming Fix
 
-### Modified
+- Fixed yargs command conflicts breaking version bumps
+- Fixed major/minor/patch bumps only incrementing Android build
+- Simplified names: `version bump <type>` → `bump <type>`
+- Default `useFvmByDefault` changed to `true`
 
-- Updated the CLI to support the latest version of Opticore.
+### 📂 [1.2.1] - Open Build Output
 
-## [1.0.3]
-### Optimized
-- Updated the CLI to support the latest version of Opticore.
+- Added `open-ipa`, `open-apk`, `open-bundle` — access build artifacts
+- Cross-platform support (macOS, Windows, Linux)
 
-## [1.0.2]
-### Enhanced
-- Improved error handling and messaging for better user experience.
+### 📱 [1.2.0] - Device Management
 
-## [1.0.1]
-### Added
-- Initial prototype with basic CLI command structure.
+- Added `devices`, `run`, `run-select` — device management commands
+- Interactive device picker with numbered prompts
+- Reorganized codebase by domain (build, clean, version, project, config)
+
+### ⚙️ [1.1.1] - VS Code Setup
+
+- Added `setup-vscode` — auto-configure VS Code for FVM
+
+### 🔄 [1.0.4] - Opticore Compatibility
+
+- Updated CLI for latest Opticore version
+
+### 🔄 [1.0.3] - Optimization
+
+- Optimized Opticore compatibility
+
+### 🛡️ [1.0.2] - Error Handling
+
+- Improved error handling and messaging
+
+### 🎉 [1.0.1] - Initial Release
+
+- First release of OptiKit CLI
+
+---
+
+Stay updated with the latest enhancements and fixes! 🚀