optikit 1.2.5 → 1.4.0

package/dist/utils/services/exec.js

@@ -1,28 +1,41 @@
-import { exec, spawn } from "child_process";
-import { promisify } from "util";
+import { spawn } from "child_process";
 import path from "path";
 import { LoggerHelpers } from "./logger.js";
+import { RETRY_CONFIG } from "../../constants.js";
+import { isDryRunMode, DryRunManager } from "../helpers/dryRun.js";
 export const iosDirectory = path.join(process.cwd(), "ios");
-const execAsync = promisify(exec);
-export function handleExecResult(err, stdout, stderr) {
-    if (err) {
-        LoggerHelpers.error(`Error: ${err.message}`);
-        return;
+/**
+ * Shared base executor with proper timeout support via setTimeout + kill.
+ * Both execCommand and execInIos delegate to this.
+ */
+function execBase(fullCommand, options = {}) {
+    const { silent = false, timeoutMs } = options;
+    // Dry-run: log the command instead of executing
+    if (isDryRunMode()) {
+        const dryRun = new DryRunManager();
+        dryRun.logCommand("Execute command", fullCommand);
+        return Promise.resolve("");
     }
-    if (stderr) {
-        LoggerHelpers.warning(`stderr: ${stderr}`);
-    }
-    if (stdout) {
-        LoggerHelpers.success(`stdout: ${stdout}`);
-    }
-}
-export async function execCommand(command) {
     return new Promise((resolve, reject) => {
-        const fullCommand = `${command}`;
-        const process = spawn(fullCommand, { shell: true });
+        const childProcess = spawn(fullCommand, { shell: true });
+        const startTime = Date.now();
         let output = "";
         let lastLogLine = "";
-        process.stdout.on("data", (data) => {
+        let killed = false;
+        // Enforce timeout via setTimeout + kill (spawn doesn't support timeout)
+        let timer;
+        if (timeoutMs && timeoutMs > 0) {
+            timer = setTimeout(() => {
+                killed = true;
+                childProcess.kill("SIGTERM");
+                reject(new Error(`Command timed out after ${timeoutMs / 1000}s: ${fullCommand}`));
+            }, timeoutMs);
+        }
+        childProcess.stdout.on("data", (data) => {
+            if (silent) {
+                output += data.toString();
+                return;
+            }
             const dataString = data.toString().trim();
             output += dataString;
             if (dataString) {
@@ -38,78 +51,29 @@ export async function execCommand(command) {
                 }
             }
         });
-        process.stderr.on("data", (data) => {
-            LoggerHelpers.error(data.toString());
-        });
-        process.on("close", (code) => {
-            if (lastLogLine) {
-                LoggerHelpers.success(lastLogLine);
-            }
-            if (code !== 0) {
-                reject(new Error(`Command failed with exit code ${code}`));
+        childProcess.stderr.on("data", (data) => {
+            if (silent) {
+                output += data.toString();
             }
             else {
-                resolve(output);
+                LoggerHelpers.error(data.toString());
             }
         });
-        process.on("error", (err) => {
-            reject(new Error(`Failed to start subprocess: ${err.message}`));
-        });
-    });
-}
-export async function execCommandSilent(command) {
-    return new Promise((resolve, reject) => {
-        const fullCommand = `${command}`;
-        const process = spawn(fullCommand, { shell: true });
-        let output = "";
-        process.stdout.on("data", (data) => {
-            output += data.toString();
-        });
-        process.stderr.on("data", (data) => {
-            output += data.toString();
-        });
-        process.on("close", (code) => {
-            if (code !== 0) {
-                reject(new Error(`Command failed with exit code ${code}`));
-            }
-            else {
-                resolve(output);
+        childProcess.on("close", (code) => {
+            if (timer)
+                clearTimeout(timer);
+            if (killed)
+                return;
+            if (!silent && lastLogLine) {
+                LoggerHelpers.success(lastLogLine);
             }
-        });
-        process.on("error", (err) => {
-            reject(new Error(`Failed to start subprocess: ${err.message}`));
-        });
-    });
-}
-export async function execInIos(command) {
-    return new Promise((resolve, reject) => {
-        const fullCommand = `cd "${iosDirectory}" && ${command}`;
-        const process = spawn(fullCommand, { shell: true, timeout: 600000 });
-        let output = "";
-        let lastLogLine = "";
-        process.stdout.on("data", (data) => {
-            const dataString = data.toString().trim();
-            output += dataString;
-            if (dataString) {
-                if ((dataString.endsWith("ms") || dataString.endsWith("s")) &&
-                    lastLogLine) {
-                    lastLogLine += ` ${dataString}`;
-                }
-                else {
-                    if (lastLogLine) {
-                        LoggerHelpers.success(lastLogLine);
-                    }
-                    lastLogLine = dataString;
+            // Show elapsed time for non-silent commands over 1 second
+            if (!silent) {
+                const elapsed = Date.now() - startTime;
+                if (elapsed > 1000) {
+                    LoggerHelpers.info(`Completed in ${formatElapsed(elapsed)}`);
                 }
             }
-        });
-        process.stderr.on("data", (data) => {
-            LoggerHelpers.error(data.toString());
-        });
-        process.on("close", (code) => {
-            if (lastLogLine) {
-                LoggerHelpers.success(lastLogLine);
-            }
             if (code !== 0) {
                 reject(new Error(`Command failed with exit code ${code}`));
             }
@@ -117,40 +81,51 @@ export async function execInIos(command) {
                 resolve(output);
             }
         });
-        process.on("error", (err) => {
+        childProcess.on("error", (err) => {
+            if (timer)
+                clearTimeout(timer);
             reject(new Error(`Failed to start subprocess: ${err.message}`));
         });
     });
 }
-export async function execInIosWithRetry(command, retries = 3, delay = 5000) {
+export async function execCommand(command) {
+    return execBase(command);
+}
+export async function execCommandSilent(command) {
+    return execBase(command, { silent: true });
+}
+export async function execInIos(command, timeoutMs = RETRY_CONFIG.IOS_TIMEOUT_MS) {
+    const fullCommand = `cd "${iosDirectory}" && ${command}`;
+    return execBase(fullCommand, { timeoutMs });
+}
+export async function execInIosWithRetry(command, retries = RETRY_CONFIG.DEFAULT_ATTEMPTS, delay = RETRY_CONFIG.DEFAULT_DELAY_MS) {
     let attempts = 0;
     let lastError;
     while (attempts < retries) {
         try {
-            const result = await execInIos(command);
-            return result;
+            return await execInIos(command);
         }
         catch (error) {
             attempts++;
             lastError = error;
-            if (error instanceof Error) {
-                LoggerHelpers.error(`Attempt ${attempts} failed. Error: ${error.message}`);
-            }
-            else {
-                LoggerHelpers.error(`Attempt ${attempts} failed. Unknown error: ${JSON.stringify(error)}`);
-            }
+            const message = error instanceof Error ? error.message : JSON.stringify(error);
+            LoggerHelpers.error(`Attempt ${attempts} failed. Error: ${message}`);
             if (attempts >= retries) {
-                if (lastError instanceof Error) {
-                    LoggerHelpers.error(`Command failed after ${retries} attempts: ${lastError.message}`);
-                }
-                else {
-                    LoggerHelpers.error(`Command failed after ${retries} attempts: Unknown error`);
-                }
-                throw new Error(`Command failed after ${retries} attempts: ${lastError instanceof Error ? lastError.message : "Unknown error"}`);
+                const finalMessage = lastError instanceof Error ? lastError.message : "Unknown error";
+                LoggerHelpers.error(`Command failed after ${retries} attempts: ${finalMessage}`);
+                throw new Error(`Command failed after ${retries} attempts: ${finalMessage}`);
             }
             LoggerHelpers.error(`Retrying in ${delay / 1000} seconds...`);
-            await new Promise(resolve => setTimeout(resolve, delay));
+            await new Promise((resolve) => setTimeout(resolve, delay));
         }
     }
     throw lastError;
 }
+function formatElapsed(ms) {
+    const seconds = Math.floor(ms / 1000);
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = seconds % 60;
+    return `${minutes}m ${remainingSeconds}s`;
+}

package/dist/utils/services/logger.js

@@ -1,15 +1,21 @@
 import chalk from "chalk";
 export class LoggerHelpers {
     static success(message) {
-        console.log(chalk.green(message));
+        console.log(chalk.green(`  ✔ ${message}`));
     }
     static error(message) {
-        console.log(chalk.red(message));
+        console.log(chalk.red(`  ✖ ${message}`));
     }
     static warning(message) {
-        console.log(chalk.yellow(message));
+        console.log(chalk.yellow(`  ⚠ ${message}`));
     }
     static info(message) {
-        console.log(chalk.hex('#add8e6')(message));
+        console.log(chalk.cyan(`  ℹ ${message}`));
+    }
+    static step(message) {
+        console.log(chalk.white(`  → ${message}`));
+    }
+    static dim(message) {
+        console.log(chalk.gray(`    ${message}`));
     }
 }

package/dist/utils/validators/validation.js

@@ -7,17 +7,21 @@ export { validateFlutterProject, validateFlutterSdk, validateIosProject, validat
  * Validates that the current directory is a Flutter project
  * by checking for pubspec.yaml
  */
-function validateFlutterProject() {
+function validateFlutterProject(silent = false) {
     const pubspecPath = path.join(process.cwd(), "pubspec.yaml");
     if (!fs.existsSync(pubspecPath)) {
-        LoggerHelpers.error("Not a Flutter project: pubspec.yaml not found.");
-        LoggerHelpers.info("Please run this command from the root of a Flutter project.");
+        if (!silent) {
+            LoggerHelpers.error("Not a Flutter project: pubspec.yaml not found.");
+            LoggerHelpers.info("Please run this command from the root of a Flutter project.");
+        }
         return false;
     }
     // Check if pubspec.yaml contains Flutter SDK
     const pubspecContent = fs.readFileSync(pubspecPath, "utf8");
     if (!pubspecContent.includes("flutter:")) {
-        LoggerHelpers.error("Not a Flutter project: pubspec.yaml does not reference Flutter SDK.");
+        if (!silent) {
+            LoggerHelpers.error("Not a Flutter project: pubspec.yaml does not reference Flutter SDK.");
+        }
         return false;
     }
     return true;
@@ -60,17 +64,21 @@ async function validateFlutterSdk(useFvm = false) {
 /**
  * Validates that the iOS project exists
  */
-function validateIosProject() {
+function validateIosProject(silent = false) {
     const iosPath = path.join(process.cwd(), "ios");
     if (!fs.existsSync(iosPath)) {
-        LoggerHelpers.error("iOS project directory not found.");
-        LoggerHelpers.info("Run 'flutter create .' to add iOS support.");
+        if (!silent) {
+            LoggerHelpers.error("iOS project directory not found.");
+            LoggerHelpers.info("Run 'flutter create .' to add iOS support.");
+        }
         return false;
     }
     const xcodeProjPath = path.join(iosPath, "Runner.xcodeproj");
     const xcworkspacePath = path.join(iosPath, "Runner.xcworkspace");
     if (!fs.existsSync(xcodeProjPath) && !fs.existsSync(xcworkspacePath)) {
-        LoggerHelpers.error("No Xcode project or workspace found in ios/ directory.");
+        if (!silent) {
+            LoggerHelpers.error("No Xcode project or workspace found in ios/ directory.");
+        }
         return false;
     }
     return true;
@@ -78,17 +86,21 @@ function validateIosProject() {
 /**
  * Validates that the Android project exists
  */
-function validateAndroidProject() {
+function validateAndroidProject(silent = false) {
     const androidPath = path.join(process.cwd(), "android");
     if (!fs.existsSync(androidPath)) {
-        LoggerHelpers.error("Android project directory not found.");
-        LoggerHelpers.info("Run 'flutter create .' to add Android support.");
+        if (!silent) {
+            LoggerHelpers.error("Android project directory not found.");
+            LoggerHelpers.info("Run 'flutter create .' to add Android support.");
+        }
         return false;
     }
     const buildGradlePath = path.join(androidPath, "build.gradle");
     const buildGradleKtsPath = path.join(androidPath, "build.gradle.kts");
     if (!fs.existsSync(buildGradlePath) && !fs.existsSync(buildGradleKtsPath)) {
-        LoggerHelpers.error("No build.gradle found in android/ directory.");
+        if (!silent) {
+            LoggerHelpers.error("No build.gradle found in android/ directory.");
+        }
         return false;
     }
     return true;

package/docs/INSTALLATION.md

@@ -0,0 +1,72 @@
+# 🔧 Installation Guide
+
+---
+
+## ⚡ NPM (Recommended)
+
+```bash
+npm install -g optikit
+```
+
+Verify:
+
+```bash
+optikit --version
+```
+
+You get two commands — `optikit` and `ok` — both work identically.
+
+---
+
+## 📦 Homebrew
+
+### Via HTTPS
+
+```bash
+brew tap dev-mahmoud-elshenawy/optikit
+brew install optikit
+```
+
+### Via SSH (Recommended)
+
+```bash
+brew tap dev-mahmoud-elshenawy/optikit git@github.com:dev-mahmoud-elshenawy/optikit.git
+brew install optikit
+```
+
+---
+
+## 🛠️ From Source
+
+```bash
+git clone https://github.com/dev-mahmoud-elshenawy/optikit.git
+cd optikit
+npm install && npm run build
+npm link
+```
+
+Verify:
+
+```bash
+optikit --version
+```
+
+---
+
+## ✅ Shell Autocomplete (Optional)
+
+Enable tab completion for all commands and flags:
+
+```bash
+optikit completion >> ~/.zshrc && source ~/.zshrc
+```
+
+---
+
+## 🚀 Next Steps
+
+```bash
+optikit init                    # Setup OptiKit in your Flutter project
+optikit aliases                 # See all commands & shortcuts
+optikit --help                  # Full help
+```

package/docs/TROUBLESHOOT.md

@@ -0,0 +1,140 @@
+# 🔍 Troubleshooting
+
+Quick fixes for common OptiKit issues.
+
+---
+
+## ❌ `optikit` or `ok` command not found
+
+```bash
+# Reinstall globally
+npm install -g optikit
+
+# Verify
+optikit --version
+```
+
+If still not found, check your npm global bin is in PATH:
+
+```bash
+npm bin -g
+# Add the output path to your shell config if missing
+```
+
+---
+
+## ❌ FVM not found
+
+```
+✖ FVM Flutter SDK not found at .fvm/flutter_sdk
+```
+
+**Fix:** Install FVM and set up the project:
+
+```bash
+fvm install
+fvm use <version>
+```
+
+Or skip FVM for this command:
+
+```bash
+optikit apk -f                  # -f = --disable-fvm
+```
+
+Or disable FVM globally in `.optikitrc.json`:
+
+```json
+{
+  "useFvmByDefault": false
+}
+```
+
+---
+
+## ❌ Not a Flutter project
+
+```
+✖ Not a Flutter project: pubspec.yaml not found.
+```
+
+**Fix:** Run OptiKit from the **root** of your Flutter project (where `pubspec.yaml` is).
+
+---
+
+## ❌ iOS / Android project not found
+
+```
+✖ iOS project directory not found.
+✖ Android project directory not found.
+```
+
+**Fix:** Add platform support:
+
+```bash
+flutter create .                # Adds missing ios/ and android/ directories
+```
+
+---
+
+## ❌ Build fails
+
+1. **Check environment first:**
+
+```bash
+optikit dr                      # Doctor checks Flutter, FVM, platforms
+```
+
+2. **Try a clean build:**
+
+```bash
+optikit apk --clean             # Clean before building
+optikit ipa --clean             # Clean before building (iOS)
+```
+
+3. **For iOS CocoaPods issues:**
+
+```bash
+optikit ci -cu                  # Clean iOS + clear cache + update repo
+```
+
+---
+
+## ❌ Wrong version after bump
+
+**Check current state:**
+
+```bash
+optikit v                       # Show current version info
+```
+
+**Restore from backup:**
+
+```bash
+optikit undo                    # List all backups
+optikit undo --restore 1        # Restore the most recent backup
+```
+
+---
+
+## ❌ Module generation overwrites existing files
+
+OptiKit warns before overwriting. If you accidentally overwrote:
+
+```bash
+# Check git for the original
+git diff lib/module/<module_name>/
+git checkout -- lib/module/<module_name>/
+```
+
+---
+
+## 💡 General Tips
+
+| Tip | Command |
+|-----|---------|
+| Check environment health | `optikit dr` |
+| Preview without executing | `optikit apk --dry-run` |
+| See all available commands | `optikit aliases` |
+| Get help for any command | `optikit <command> --help` |
+| Check for CLI updates | `optikit up` |