optikit 1.2.5 → 1.3.0

package/docs/USAGE.md

@@ -0,0 +1,185 @@
+# 📖 Command Reference
+
+> Use `optikit` or `ok` — both work identically. Run `optikit aliases` to see all shortcuts.
+
+---
+
+## 🏗️ Build
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `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 before building
+optikit apk -o                  # 📂 Open output folder after build
+optikit apk -b patch            # 📦 Bump patch version before build
+optikit apk -b minor -o         # 📦 Bump minor + build + open
+optikit ipa -i                  # 📱 Bump iOS build number before build
+optikit ipa --clean -i -o       # 🚀 Full workflow: clean → bump iOS → build → open
+optikit tf -o                   # 🚀 TestFlight + open output
+```
+
+| Flag | Short | Applies to |
+|------|-------|-----------|
+| `--clean` | | apk, aab, ios, ipa |
+| `--open` | `-o` | apk, aab, ipa, tf |
+| `--bump <type>` | `-b` | apk, aab, ios, ipa |
+| `--bump-ios` | `-i` | ipa |
+| `--disable-fvm` | `-f` | all |
+
+---
+
+## 🧹 Clean
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `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 clean -i                # Clean Flutter + also iOS
+optikit ci -c                   # Clean iOS + clear cache
+optikit ci -u                   # Clean iOS + update repo
+optikit ci -cu                  # Clean iOS + cache + repo update
+```
+
+| Flag | Short | Command |
+|------|-------|---------|
+| `--all` | `-a` | clean |
+| `--ios` | `-i` | clean |
+| `--clean-cache` | `-c` | clean-ios |
+| `--repo-update` | `-u` | clean-ios |
+| `--disable-fvm` | `-f` | clean, clean-flutter |
+
+---
+
+## 📦 Version & Bump
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `optikit version` | `v` | Show current version info |
+| `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 |
+| `optikit flutter-update-version` | `vset` | Set version manually |
+
+```bash
+optikit vset --app-version 2.0.0 --android-build 10 --ios-build 1
+```
+
+Add `-y` to skip confirmation: `optikit bump patch -y`
+
+> 📘 Deep dive: **[Version Management](VERSION_MANAGEMENT.md)**
+
+---
+
+## 🧩 Generate
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `optikit generate module <name>` | `gen module` | Scaffold BLoC module |
+| `optikit generate repo <name>` | `gen repo` | Generate repository file |
+| `optikit add-route <name>` | `route` | Add route to app_router.dart |
+
+```bash
+optikit gen module login -r     # 🧩 Scaffold + register route
+```
+
+Module creates: `bloc`, `event`, `state`, `screen`, `factory`, and `imports` files.
+
+---
+
+## 📱 Run & Devices
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `optikit run` | | Run app on connected device |
+| `optikit run-select` | `rs` | Interactive device picker |
+| `optikit devices` | `devs` | List connected devices |
+
+```bash
+optikit run -r                  # Run in release mode
+optikit run -d <id>             # Run on specific device
+optikit rs -r                   # Pick device + release mode
+```
+
+---
+
+## 🔗 Open
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `optikit open-ios` | `xcode` | Open in Xcode |
+| `optikit open-android` | `studio` | Open in Android Studio |
+| `optikit open-ipa` | | Open IPA output folder |
+| `optikit open-apk` | | Open APK output folder |
+| `optikit open-bundle` | | Open AAB output folder |
+
+> 💡 Use `optikit ipa -o` or `optikit apk -o` to build and open in one step.
+
+---
+
+## 🔧 Config & Tools
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `optikit init` | | Initialize OptiKit config |
+| `optikit init-app` | | Scaffold Opticore app structure |
+| `optikit setup-vscode` | `vscode` | Create VS Code Flutter settings |
+| `optikit rollback` | `undo` | List/restore file backups |
+| `optikit status` | `info` | Project status snapshot |
+| `optikit doctor` | `dr` | Environment health check |
+| `optikit upgrade` | `up` | Check for CLI updates |
+| `optikit aliases` | | Show all aliases & shortcuts |
+
+```bash
+optikit undo --restore 1        # Restore backup #1
+optikit undo --before 2026-03-20  # Show backups before date
+```
+
+---
+
+## 🌐 Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--dry-run` | | Preview without executing |
+| `--disable-fvm` | `-f` | Use global Flutter SDK |
+| `--help` | | Show command help |
+| `--version` | | Show CLI version |
+
+---
+
+## 📋 All Aliases
+
+| Alias | Command | Alias | Command |
+|-------|---------|-------|---------|
+| `apk` | flutter-build-apk | `gen` | generate |
+| `aab` | flutter-build-bundle | `route` | add-route |
+| `ios` | flutter-build-ios | `xcode` | open-ios |
+| `ipa` | flutter-build-ipa | `studio` | open-android |
+| `tf` | testflight | `vscode` | setup-vscode |
+| `c` | clean | `devs` | devices |
+| `cf` | clean-flutter | `rs` | run-select |
+| `ci` | clean-ios | `info` | status |
+| `v` | version | `dr` | doctor |
+| `bi` | bump-ios | `undo` | rollback |
+| `ba` | bump-android | `up` | upgrade |
+| `bb` | bump-build | | |
+| `vset` | flutter-update-version | | |
+
+Or run `optikit aliases` to see this in your terminal.

package/docs/VERSION_MANAGEMENT.md

@@ -0,0 +1,177 @@
+# 📦 Version Management
+
+OptiKit handles Flutter's dual build number system (iOS + Android) automatically.
+
+---
+
+## 🎯 The Problem
+
+Flutter apps have **two independent build numbers**:
+
+| Platform | Where | Rule |
+|----------|-------|------|
+| 🤖 **Android** | `pubspec.yaml` (`1.0.0+5`) | Must always increase |
+| 🍎 **iOS** | Xcode project files | Resets per version |
+
+Different stores, different rules. OptiKit handles both.
+
+---
+
+## 📋 Commands
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `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 |
+| `optikit testflight` | `tf` | Bump iOS + build IPA |
+| `optikit flutter-update-version` | `vset` | Set version manually |
+
+---
+
+## ⚙️ What Each Command Does
+
+### `optikit bump <type>` — New Version Release
+
+| | Version | Android Build | iOS Build |
+|---|---------|--------------|-----------|
+| Before | 1.0.2 | +45 | 3 |
+| After `bump patch` | **1.0.3** | **+46** | **1** (reset) |
+
+✅ Increments version &nbsp; ✅ Increments Android build &nbsp; ✅ Resets iOS build to 1
+
+### `optikit bump-ios` — TestFlight Upload
+
+| | Version | Android Build | iOS Build |
+|---|---------|--------------|-----------|
+| Before | 1.0.3 | +46 | 1 |
+| After `bi` | 1.0.3 | +46 | **2** |
+
+Only iOS build changes. Perfect for multiple TestFlight iterations.
+
+### `optikit bump-android` — Play Store Upload
+
+| | Version | Android Build | iOS Build |
+|---|---------|--------------|-----------|
+| Before | 1.0.3 | +46 | 2 |
+| After `ba` | 1.0.3 | **+47** | 2 |
+
+Only Android build changes.
+
+### `optikit bump-build` — Both Platforms
+
+Increments both Android and iOS build numbers. Version stays the same.
+
+---
+
+## 🚀 Real Workflows
+
+### 📱 TestFlight Iterations
+
+```bash
+optikit bump minor              # New version: 1.3.0 (iOS build: 1)
+optikit tf -o                   # Build 1 → TestFlight + open
+# ... fix a bug ...
+optikit tf -o                   # Build 2 → TestFlight + open
+# ... another fix ...
+optikit tf -o                   # Build 3 → TestFlight + open
+```
+
+### 🤖 Android Hotfix
+
+```bash
+optikit ba                      # Bump Android build only
+optikit apk -o                  # Build + open APK
+```
+
+### 🔄 Complete Release Cycle
+
+```bash
+# Start: 1.0.2+10 (iOS: 5)
+optikit bump minor              # → 1.1.0+11 (iOS: 1)
+
+# TestFlight testing
+optikit tf                      # iOS: 2
+optikit tf                      # iOS: 3
+optikit tf                      # iOS: 4
+
+# Android testing
+optikit ba                      # Android: 12
+
+# Bug found, patch it
+optikit bump patch              # → 1.1.1+13 (iOS: 1)
+
+# Final builds
+optikit tf -o                   # iOS: 2, open output
+optikit apk -o                  # Android: 13, open output
+
+# 🚀 Ship it!
+```
+
+---
+
+## 📁 Files Updated
+
+Every version command updates up to 3 files:
+
+| File | What changes |
+|------|-------------|
+| `pubspec.yaml` | `version: X.Y.Z+B` |
+| `ios/Runner.xcodeproj/project.pbxproj` | `MARKETING_VERSION`, `CURRENT_PROJECT_VERSION` |
+| `ios/Runner/Info.plist` | `CFBundleShortVersionString`, `CFBundleVersion` |
+
+All files are **backed up automatically** before changes. Use `optikit undo` to restore.
+
+---
+
+## 🔢 Version Format
+
+```
+pubspec.yaml:  version: 1.2.3+45
+                         │ │ │  │
+                         │ │ │  └── Android build number
+                         │ │ └──── Patch
+                         │ └────── Minor
+                         └──────── Major
+
+iOS (separate):
+  CFBundleShortVersionString: 1.2.3    (display version)
+  CFBundleVersion:            1, 2, 3  (build number, resets per version)
+```
+
+---
+
+## ❓ Why iOS Resets to 1
+
+App Store Connect requires unique build numbers **per version**, not globally:
+
+```
+📱 Version 1.0.0
+   Build 1, Build 2, Build 3 ✅ Released
+
+📱 Version 1.0.1
+   Build 1  ← starts fresh
+   Build 2, Build 3 ✅ Released
+```
+
+Android is the opposite — Google Play requires **strictly increasing** build numbers across all versions.
+
+OptiKit handles both strategies automatically.
+
+---
+
+## 📊 Quick Reference
+
+| Command | Version | Android | iOS | Use case |
+|---------|---------|---------|-----|----------|
+| `bump patch` | +0.0.1 | +1 | Reset to 1 | 🐛 Bug fix |
+| `bump minor` | +0.1.0 | +1 | Reset to 1 | ✨ New feature |
+| `bump major` | +1.0.0 | +1 | Reset to 1 | 💥 Breaking change |
+| `bi` | -- | -- | +1 | 📱 TestFlight |
+| `ba` | -- | +1 | -- | 🤖 Play Store |
+| `bb` | -- | +1 | +1 | 📱🤖 Both |
+| `tf` | -- | -- | +1 + build IPA | 🚀 TestFlight shortcut |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "optikit",
-  "version": "1.2.5",
+  "version": "1.3.0",
   "description": "OptiKit CLI",
   "main": "src/cli.ts",
   "type": "module",
@@ -10,7 +10,8 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "bin": {
-    "optikit": "dist/cli.js"
+    "optikit": "dist/cli.js",
+    "ok": "dist/cli.js"
   },
   "keywords": [
     "optikit",
@@ -21,21 +22,16 @@
   "author": "Mahmoud El Shenawy",
   "license": "ISC",
   "dependencies": {
-    "arg": "^5.0.2",
+    "@modelcontextprotocol/sdk": "^1.28.0",
     "boxen": "^8.0.1",
     "chalk": "^4.1.2",
-    "esm": "^3.2.25",
-    "yargs": "^17.7.2"
+    "yargs": "^17.7.2",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@babel/core": "7.26.0",
-    "@babel/preset-env": "7.26.0",
-    "@babel/preset-react": "7.26.3",
     "@types/boxen": "^3.0.1",
     "@types/node": "^20.0.0",
     "@types/yargs": "^17.0.33",
-    "babel-loader": "9.2.1",
-    "ts-node": "^10.9.1",
     "typescript": "^5.6.3"
   }
-}
+}