optikit 1.1.0 → 1.2.0

package/VERSION_MANAGEMENT.md

@@ -0,0 +1,438 @@
+# OptiKit CLI - Smart Version Management
+
+## Overview
+
+OptiKit provides intelligent version management that handles the complexities of Flutter's dual build number system (iOS and Android) automatically.
+
+---
+
+## 🎯 The Problem
+
+Flutter apps have **two separate build numbers**:
+- **Android**: Single build number in `pubspec.yaml` (e.g., `1.0.0+5`)
+- **iOS**: Separate build number in Xcode project
+
+**Common scenarios:**
+1. **New version release** → Increment version, reset iOS build to 1, increment Android build
+2. **TestFlight upload** → Keep version same, only increment iOS build
+3. **Google Play upload** → Keep version same, only increment Android build
+
+OptiKit handles all these scenarios automatically!
+
+---
+
+## 📱 Commands
+
+### 1. Show Current Version
+
+```bash
+optikit version
+```
+
+**Output:**
+```
+📱 Current Version Information
+
+Version: 1.2.3+45
+  Major: 1
+  Minor: 2
+  Patch: 3
+  Build: 45
+```
+
+---
+
+### 2. Bump Version (Semantic Versioning)
+
+#### Bump Patch (1.2.3 → 1.2.4)
+```bash
+optikit version bump patch
+```
+
+**What it does:**
+- Increments patch number: `1.2.3` → `1.2.4`
+- Increments Android build: `45` → `46`
+- **Resets iOS build to 1** (new version = fresh start)
+
+**Use when:**
+- Bug fixes
+- Minor updates
+- No new features
+
+#### Bump Minor (1.2.4 → 1.3.0)
+```bash
+optikit version bump minor
+```
+
+**What it does:**
+- Increments minor number: `1.2` → `1.3`
+- Resets patch to 0: `1.2.4` → `1.3.0`
+- Increments Android build: `46` → `47`
+- **Resets iOS build to 1**
+
+**Use when:**
+- New features added
+- Backward-compatible changes
+
+#### Bump Major (1.3.0 → 2.0.0)
+```bash
+optikit version bump major
+```
+
+**What it does:**
+- Increments major number: `1` → `2`
+- Resets minor and patch to 0: `1.3.0` → `2.0.0`
+- Increments Android build: `47` → `48`
+- **Resets iOS build to 1**
+
+**Use when:**
+- Breaking changes
+- Major redesign
+- Complete rewrite
+
+---
+
+### 3. Bump iOS Build Only (TestFlight)
+
+```bash
+optikit version bump-ios
+```
+
+**What it does:**
+- **Only** increments iOS build number
+- Keeps version unchanged
+- Keeps Android build unchanged
+
+**Example:**
+```
+Before:
+  Version: 1.2.3
+  Android: 45
+  iOS: 1
+
+After:
+  Version: 1.2.3 (unchanged)
+  Android: 45 (unchanged)
+  iOS: 2 ✅
+```
+
+**Use when:**
+- Uploading to TestFlight
+- iOS-only fixes
+- Testing iOS-specific features
+
+---
+
+### 4. Bump Android Build Only
+
+```bash
+optikit version bump-android
+```
+
+**What it does:**
+- **Only** increments Android build number
+- Keeps version unchanged
+- Keeps iOS build unchanged
+
+**Example:**
+```
+Before:
+  Version: 1.2.3+45
+  iOS: 1
+
+After:
+  Version: 1.2.3+46 ✅
+  iOS: 1 (unchanged)
+```
+
+**Use when:**
+- Uploading to Google Play
+- Android-only fixes
+- Testing Android-specific features
+
+---
+
+## 📊 Version Strategy
+
+### Scenario 1: New App Version Release
+
+**Goal:** Release version 1.0.3 (from 1.0.2)
+
+```bash
+# Current: 1.0.2+5
+optikit version bump patch
+
+# Result:
+# Version: 1.0.3+6
+# iOS build: 1 (reset)
+# Android build: 6 (incremented)
+```
+
+**Why iOS resets to 1?**
+- New version = new submission to App Store
+- Build numbers restart for each version in App Store Connect
+- This matches Apple's expectation
+
+---
+
+### Scenario 2: Multiple TestFlight Builds
+
+**Goal:** Upload multiple iOS test builds without changing version
+
+```bash
+# Current: 1.0.3+6 (iOS build: 1)
+
+# First TestFlight upload
+optikit version bump-ios
+# Version: 1.0.3+6, iOS: 2
+
+# Found a bug, fix it, upload again
+optikit version bump-ios
+# Version: 1.0.3+6, iOS: 3
+
+# Another fix
+optikit version bump-ios
+# Version: 1.0.3+6, iOS: 4
+```
+
+**Perfect for:**
+- Internal testing
+- Beta testing
+- Multiple TestFlight iterations
+
+---
+
+### Scenario 3: Android Hotfix
+
+**Goal:** Fix Android-only bug and upload to Google Play
+
+```bash
+# Current: 1.0.3+6 (iOS: 4)
+
+# Increment Android build only
+optikit version bump-android
+# Version: 1.0.3+7, iOS: 4 (unchanged)
+```
+
+---
+
+### Scenario 4: Complete Release Cycle
+
+```bash
+# 1. Start: 1.0.2+10 (iOS: 5)
+
+# 2. New feature development
+optikit version bump minor
+# → 1.1.0+11 (iOS: 1, Android: 11)
+
+# 3. TestFlight testing (3 iterations)
+optikit version bump-ios  # iOS: 2
+optikit version bump-ios  # iOS: 3
+optikit version bump-ios  # iOS: 4
+
+# 4. Android beta testing
+optikit version bump-android  # Android: 12
+
+# 5. Fix found during testing
+optikit version bump patch
+# → 1.1.1+13 (iOS: 1, Android: 13)
+
+# 6. Final TestFlight
+optikit version bump-ios  # iOS: 2
+
+# 7. Release to stores!
+# iOS: 1.1.1 (build 2)
+# Android: 1.1.1 (build 13)
+```
+
+---
+
+## 🎨 Visual Examples
+
+### Example 1: Patch Bump
+
+```
+BEFORE:                    AFTER:
+┌─────────────┐           ┌─────────────┐
+│ Version     │           │ Version     │
+│   1.2.3     │   ───>    │   1.2.4     │  ✅ Patch +1
+│             │           │             │
+│ Android: 45 │   ───>    │ Android: 46 │  ✅ Build +1
+│ iOS: 3      │   ───>    │ iOS: 1      │  ✅ Reset to 1
+└─────────────┘           └─────────────┘
+
+Command: optikit version bump patch
+```
+
+### Example 2: iOS-Only Bump
+
+```
+BEFORE:                    AFTER:
+┌─────────────┐           ┌─────────────┐
+│ Version     │           │ Version     │
+│   1.2.4     │   ───>    │   1.2.4     │  ⏸️  Unchanged
+│             │           │             │
+│ Android: 46 │   ───>    │ Android: 46 │  ⏸️  Unchanged
+│ iOS: 1      │   ───>    │ iOS: 2      │  ✅ Build +1
+└─────────────┘           └─────────────┘
+
+Command: optikit version bump-ios
+```
+
+---
+
+## 🔍 Technical Details
+
+### File Updates
+
+#### Version Bump Commands Update:
+1. **pubspec.yaml**: `version: X.Y.Z+B`
+2. **iOS project.pbxproj**: `MARKETING_VERSION` and `CURRENT_PROJECT_VERSION`
+3. **iOS Info.plist**: `CFBundleShortVersionString` and `CFBundleVersion`
+
+#### Automatic Backups:
+All files are backed up before modification (see [SAFETY_FEATURES.md](SAFETY_FEATURES.md))
+
+### Version Format
+
+**pubspec.yaml:**
+```yaml
+version: 1.2.3+45
+         │ │ │  │
+         │ │ │  └─ Build number (Android)
+         │ │ └──── Patch
+         │ └────── Minor
+         └──────── Major
+```
+
+**iOS (separate):**
+- **CFBundleShortVersionString**: `1.2.3` (display version)
+- **CFBundleVersion**: `1`, `2`, `3`... (build number)
+
+---
+
+## 📋 Command Reference
+
+| Command | Version | Android Build | iOS Build | Use Case |
+|---------|---------|---------------|-----------|----------|
+| `version bump patch` | +0.0.1 | +1 | Reset to 1 | Bug fixes |
+| `version bump minor` | +0.1.0 | +1 | Reset to 1 | New features |
+| `version bump major` | +1.0.0 | +1 | Reset to 1 | Breaking changes |
+| `version bump-ios` | No change | No change | +1 | TestFlight builds |
+| `version bump-android` | No change | +1 | No change | Google Play builds |
+
+---
+
+## 🎯 Best Practices
+
+### 1. Always Use Semantic Versioning
+```bash
+# Bug fix
+optikit version bump patch
+
+# New feature
+optikit version bump minor
+
+# Breaking change
+optikit version bump major
+```
+
+### 2. TestFlight Workflow
+```bash
+# Create new version
+optikit version bump minor
+
+# Multiple TestFlight uploads
+optikit version bump-ios  # Upload 1
+optikit version bump-ios  # Upload 2
+optikit version bump-ios  # Upload 3
+
+# When satisfied, release to App Store
+# (No additional command needed)
+```
+
+### 3. Hotfix Workflow
+```bash
+# iOS hotfix
+optikit version bump patch
+optikit flutter-build-ipa
+
+# Android hotfix
+optikit version bump patch
+optikit flutter-build-bundle
+```
+
+### 4. Check Before Bumping
+```bash
+# Always check current version first
+optikit version
+
+# Then bump
+optikit version bump patch
+```
+
+---
+
+## ⚠️ Important Notes
+
+### iOS Build Number Strategy
+
+**Why reset to 1?**
+- App Store Connect requires unique build numbers **per version**
+- Build 1 of version 1.0.0 ≠ Build 1 of version 1.0.1
+- This matches Apple's system and prevents confusion
+
+**Example:**
+```
+App Store Connect:
+├── 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 Build Number Strategy
+
+**Why always increment?**
+- Google Play requires strictly increasing build numbers
+- Build 45 < Build 46 < Build 47
+- Never reset, always increment
+
+---
+
+## 🚀 Quick Reference
+
+```bash
+# Show current version
+optikit version
+
+# Release new version
+optikit version bump patch    # 1.0.0 → 1.0.1
+optikit version bump minor    # 1.0.1 → 1.1.0
+optikit version bump major    # 1.1.0 → 2.0.0
+
+# TestFlight only
+optikit version bump-ios
+
+# Google Play only
+optikit version bump-android
+```
+
+---
+
+## 📖 Related Documentation
+
+- [ENHANCEMENTS.md](ENHANCEMENTS.md) - Bug fixes
+- [SAFETY_FEATURES.md](SAFETY_FEATURES.md) - Backups & validation
+- [CODE_QUALITY.md](CODE_QUALITY.md) - Architecture
+- [FEATURE_ENHANCEMENTS.md](FEATURE_ENHANCEMENTS.md) - New features
+
+---
+
+**Version:** 1.1.1+smart-versioning
+**Last Updated:** December 23, 2025
+**Status:** ✅ Production Ready

package/dist/cli.js

@@ -3,14 +3,19 @@ import chalk from "chalk";
 import boxen from "boxen";
 import yargs from "yargs/yargs";
 import { hideBin } from "yargs/helpers";
-import { generateModule } from "./commands/generateModule.js";
-import { cleanProject } from "./commands/cleanProject.js";
-import { cleanIosProject } from "./commands/cleanProjectIos.js";
-import { updateFlutterVersion } from "./commands/updateVersions.js";
-import { buildFlutterApk, buildFlutterBundle, buildFlutterIos, buildFlutterIpa, } from "./commands/buildReleases.js";
+import { generateModule } from "./commands/project/generate.js";
+import { cleanProject } from "./commands/clean/flutter.js";
+import { cleanIosProject } from "./commands/clean/ios.js";
+import { updateFlutterVersion } from "./commands/version/update.js";
+import { buildFlutterApk, buildFlutterBundle, buildFlutterIos, buildFlutterIpa, } from "./commands/build/releases.js";
 import { boxenOptions } from "./styles.js";
-import { openIos, openAndroid } from "./commands/openProject.js";
+import { openIos, openAndroid } from "./commands/project/open.js";
 import { createRequire } from "module";
+import { createVscodeSettings } from "./commands/project/setup.js";
+import { initializeProject } from "./commands/config/init.js";
+import { rollbackFiles, rollbackRestore } from "./commands/config/rollback.js";
+import { bumpVersion, bumpIosBuildOnly, bumpAndroidBuildOnly, showCurrentVersion } from "./commands/version/bump.js";
+import { listDevices, runApp, runAppInteractive } from "./commands/project/devices.js";
 const require = createRequire(import.meta.url);
 const packageInfo = require("../package.json");
 const version = packageInfo.version;
@@ -124,6 +129,113 @@ const options = yargs(hideBin(process.argv))
 })
     .command("open-android", "Open the Android project in Android Studio", {}, async () => {
     await openAndroid();
+}).command("setup-vscode", "Create a .vscode folder with recommended Flutter settings", () => { }, async () => {
+    await createVscodeSettings();
+})
+    .command("init", "Initialize OptiKit configuration in the current project", () => { }, async () => {
+    await initializeProject();
+})
+    .command("rollback", "List and restore files from OptiKit backups", (yargs) => {
+    return yargs.option("restore", {
+        type: "number",
+        description: "Restore backup by index number",
+        demandOption: false,
+    });
+}, async (argv) => {
+    const restoreIndex = argv.restore;
+    if (restoreIndex !== undefined) {
+        await rollbackRestore(restoreIndex);
+    }
+    else {
+        await rollbackFiles();
+    }
+})
+    .command("version", "Show current version information", () => { }, async () => {
+    await showCurrentVersion();
+})
+    .command("version bump <type>", "Bump version (major, minor, or patch)", (yargs) => {
+    return yargs.positional("type", {
+        describe: "Version bump type (major, minor, patch)",
+        type: "string",
+        choices: ["major", "minor", "patch"],
+    });
+}, async (argv) => {
+    const type = argv.type;
+    await bumpVersion(type);
+})
+    .command("version bump-ios", "Increment iOS build number only (for TestFlight)", () => { }, async () => {
+    await bumpIosBuildOnly();
+})
+    .command("version bump-android", "Increment Android build number only", () => { }, async () => {
+    await bumpAndroidBuildOnly();
+})
+    .command("devices", "List all connected devices", (yargs) => {
+    return yargs.option("disable-fvm", {
+        type: "boolean",
+        default: false,
+        description: "Run without FVM (use --disable-fvm to enable)",
+    });
+}, async (argv) => {
+    const useFvm = !argv.disableFvm;
+    await listDevices(useFvm);
+})
+    .command("run", "Run Flutter app on connected device", (yargs) => {
+    return yargs
+        .option("device", {
+        alias: "d",
+        type: "string",
+        description: "Specific device ID to run on",
+    })
+        .option("release", {
+        alias: "r",
+        type: "boolean",
+        default: false,
+        description: "Run in release mode",
+    })
+        .option("flavor", {
+        alias: "f",
+        type: "string",
+        description: "Build flavor to use",
+    })
+        .option("disable-fvm", {
+        type: "boolean",
+        default: false,
+        description: "Run without FVM (use --disable-fvm to enable)",
+    });
+}, async (argv) => {
+    const useFvm = !argv.disableFvm;
+    await runApp({
+        device: argv.device,
+        release: argv.release,
+        flavor: argv.flavor,
+        useFvm,
+    });
+})
+    .command("run-select", "Interactive device selection and run", (yargs) => {
+    return yargs
+        .option("release", {
+        alias: "r",
+        type: "boolean",
+        default: false,
+        description: "Run in release mode",
+    })
+        .option("flavor", {
+        alias: "f",
+        type: "string",
+        description: "Build flavor to use",
+    })
+        .option("disable-fvm", {
+        type: "boolean",
+        default: false,
+        description: "Run without FVM (use --disable-fvm to enable)",
+    });
+}, async (argv) => {
+    const useFvm = !argv.disableFvm;
+    await runAppInteractive({
+        release: argv.release,
+        flavor: argv.flavor,
+        useFvm,
+    });
 })
     .version(version)
     .help(true).argv;

package/dist/commands/build/releases.js

@@ -0,0 +1,57 @@
+import { executeBuild } from "../../utils/helpers/build.js";
+import { BUILD_CONFIGS } from "../../constants.js";
+export { buildFlutterApk, buildFlutterBundle, buildFlutterIos, buildFlutterIpa, };
+/**
+ * Builds Flutter APK with release configuration, obfuscation, and split debug info
+ * @param noFvm - Whether to disable FVM usage
+ */
+async function buildFlutterApk(noFvm) {
+    await executeBuild({
+        type: "APK",
+        command: "flutter build apk",
+        flags: [
+            ...BUILD_CONFIGS.APK.flags,
+            `--split-debug-info=${BUILD_CONFIGS.APK.outputPath}`,
+        ],
+        requireAndroid: true,
+    }, noFvm);
+}
+/**
+ * Builds Flutter App Bundle with release configuration, obfuscation, and split debug info
+ * @param noFvm - Whether to disable FVM usage
+ */
+async function buildFlutterBundle(noFvm) {
+    await executeBuild({
+        type: "Bundle",
+        command: "flutter build appbundle",
+        flags: [
+            ...BUILD_CONFIGS.BUNDLE.flags,
+            `--split-debug-info=${BUILD_CONFIGS.BUNDLE.outputPath}`,
+        ],
+        requireAndroid: true,
+    }, noFvm);
+}
+/**
+ * Builds Flutter iOS app with release configuration
+ * @param noFvm - Whether to disable FVM usage
+ */
+async function buildFlutterIos(noFvm) {
+    await executeBuild({
+        type: "iOS app",
+        command: "flutter build ios",
+        flags: [...BUILD_CONFIGS.IOS.flags],
+        requireIos: true,
+    }, noFvm);
+}
+/**
+ * Creates release IPA with updated build version number
+ * @param noFvm - Whether to disable FVM usage
+ */
+async function buildFlutterIpa(noFvm) {
+    await executeBuild({
+        type: "IPA",
+        command: "flutter build ipa",
+        flags: [...BUILD_CONFIGS.IPA.flags],
+        requireIos: true,
+    }, noFvm);
+}