optikit 1.2.5 → 1.3.0

package/dist/commands/mcp/tools.js

@@ -0,0 +1,359 @@
+import { z } from "zod";
+import { buildFlutterApk, buildFlutterBundle, buildFlutterIos, buildFlutterIpa } from "../build/releases.js";
+import { runTestflight } from "../build/testflight.js";
+import { cleanProject } from "../clean/flutter.js";
+import { cleanIosProject } from "../clean/ios.js";
+import { bumpVersion, bumpIosBuildOnly, bumpAndroidBuildOnly, bumpBothBuilds, showCurrentVersion } from "../version/bump.js";
+import { updateFlutterVersion } from "../version/update.js";
+import { generateModule, generateRepoModule, addRoute } from "../project/generate.js";
+import { openIos, openAndroid, openIpaOutput, openApkOutput, openBundleOutput } from "../project/open.js";
+import { listDevices, runApp } from "../project/devices.js";
+import { showStatus } from "../project/status.js";
+import { runDoctor } from "../project/doctor.js";
+import { initializeProject } from "../config/init.js";
+import { initOpticoreApp } from "../config/initApp.js";
+import { rollbackFiles, rollbackRestore } from "../config/rollback.js";
+import { createVscodeSettings } from "../project/setup.js";
+import { checkUpgrade } from "../config/upgrade.js";
+async function captureOutput(fn) {
+    const lines = [];
+    const origLog = console.log;
+    const origError = console.error;
+    console.log = (...args) => lines.push(args.map(String).join(" "));
+    console.error = (...args) => lines.push(args.map(String).join(" "));
+    try {
+        await fn();
+    }
+    finally {
+        console.log = origLog;
+        console.error = origError;
+    }
+    return lines.join("\n") || "Done.";
+}
+export const tools = [
+    // ── Build ──
+    {
+        name: "build_apk",
+        description: "Build a Flutter APK for Android. Use when the user needs an APK for testing, distribution, or Play Store upload. Supports cleaning before build, bumping version, and opening output.",
+        schema: z.object({
+            disableFvm: z.boolean().optional().describe("Use global Flutter SDK instead of FVM"),
+            clean: z.boolean().optional().describe("Clean project before building"),
+            bump: z.enum(["major", "minor", "patch"]).optional().describe("Bump version before building"),
+            open: z.boolean().optional().describe("Open output directory after build"),
+        }),
+        handler: async (args) => {
+            if (args.bump)
+                await bumpVersion(args.bump, true);
+            if (args.clean)
+                await cleanProject(args.disableFvm ?? false);
+            await buildFlutterApk(args.disableFvm ?? false);
+            if (args.open)
+                await openApkOutput();
+            return "APK build completed.";
+        },
+    },
+    {
+        name: "build_aab",
+        description: "Build a Flutter App Bundle (AAB) for Google Play Store. Use when the user needs an Android release bundle for store submission.",
+        schema: z.object({
+            disableFvm: z.boolean().optional().describe("Use global Flutter SDK instead of FVM"),
+            clean: z.boolean().optional().describe("Clean project before building"),
+            bump: z.enum(["major", "minor", "patch"]).optional().describe("Bump version before building"),
+            open: z.boolean().optional().describe("Open output directory after build"),
+        }),
+        handler: async (args) => {
+            if (args.bump)
+                await bumpVersion(args.bump, true);
+            if (args.clean)
+                await cleanProject(args.disableFvm ?? false);
+            await buildFlutterBundle(args.disableFvm ?? false);
+            if (args.open)
+                await openBundleOutput();
+            return "AAB bundle build completed.";
+        },
+    },
+    {
+        name: "build_ios",
+        description: "Build the Flutter iOS app in release mode. Use when the user wants to compile for iOS without creating an IPA archive.",
+        schema: z.object({
+            disableFvm: z.boolean().optional().describe("Use global Flutter SDK instead of FVM"),
+            clean: z.boolean().optional().describe("Clean project before building"),
+            bump: z.enum(["major", "minor", "patch"]).optional().describe("Bump version before building"),
+        }),
+        handler: async (args) => {
+            if (args.bump)
+                await bumpVersion(args.bump, true);
+            if (args.clean) {
+                await cleanProject(args.disableFvm ?? false);
+                await cleanIosProject(false, false);
+            }
+            await buildFlutterIos(args.disableFvm ?? false);
+            return "iOS build completed.";
+        },
+    },
+    {
+        name: "build_ipa",
+        description: "Create a release IPA for TestFlight or App Store distribution. Use when the user wants to distribute an iOS build or upload to TestFlight.",
+        schema: z.object({
+            disableFvm: z.boolean().optional().describe("Use global Flutter SDK instead of FVM"),
+            clean: z.boolean().optional().describe("Clean project before building"),
+            bump: z.enum(["major", "minor", "patch"]).optional().describe("Bump version before building"),
+            bumpIos: z.boolean().optional().describe("Bump iOS build number before building"),
+            open: z.boolean().optional().describe("Open output directory after build"),
+        }),
+        handler: async (args) => {
+            if (args.bump)
+                await bumpVersion(args.bump, true);
+            if (args.bumpIos)
+                await bumpIosBuildOnly(true);
+            if (args.clean) {
+                await cleanProject(args.disableFvm ?? false);
+                await cleanIosProject(false, false);
+            }
+            await buildFlutterIpa(args.disableFvm ?? false);
+            if (args.open)
+                await openIpaOutput();
+            return "IPA build completed.";
+        },
+    },
+    {
+        name: "testflight",
+        description: "Full TestFlight workflow: bump iOS build number then build IPA. Use when preparing a new iOS build for TestFlight beta testing.",
+        schema: z.object({
+            disableFvm: z.boolean().optional().describe("Use global Flutter SDK instead of FVM"),
+            open: z.boolean().optional().describe("Open IPA output directory after build"),
+        }),
+        handler: async (args) => {
+            await runTestflight(args.disableFvm ?? false, args.open ?? false);
+            return "TestFlight build completed.";
+        },
+    },
+    // ── Clean ──
+    {
+        name: "clean",
+        description: "Clean the Flutter project. Use when builds fail due to stale caches, after switching branches, or before a fresh release build. Can also clean iOS CocoaPods.",
+        schema: z.object({
+            disableFvm: z.boolean().optional().describe("Use global Flutter SDK instead of FVM"),
+            ios: z.boolean().optional().describe("Also clean iOS project"),
+            all: z.boolean().optional().describe("Clean both Flutter and iOS"),
+            cleanCache: z.boolean().optional().describe("Clear CocoaPods cache (iOS)"),
+            repoUpdate: z.boolean().optional().describe("Update CocoaPods spec repo (iOS)"),
+        }),
+        handler: async (args) => {
+            await cleanProject(args.disableFvm ?? false);
+            if (args.ios || args.all) {
+                await cleanIosProject(args.cleanCache ?? false, args.repoUpdate ?? false);
+            }
+            return args.all || args.ios ? "Flutter and iOS cleaned." : "Flutter project cleaned.";
+        },
+    },
+    {
+        name: "clean_ios",
+        description: "Clean only the iOS project: remove Pods, deintegrate CocoaPods. Use when iOS builds fail but Flutter is fine, or when CocoaPods has cache issues.",
+        schema: z.object({
+            cleanCache: z.boolean().optional().describe("Clear CocoaPods cache"),
+            repoUpdate: z.boolean().optional().describe("Update CocoaPods spec repo"),
+        }),
+        handler: async (args) => {
+            await cleanIosProject(args.cleanCache ?? false, args.repoUpdate ?? false);
+            return "iOS project cleaned.";
+        },
+    },
+    // ── Version ──
+    {
+        name: "bump_version",
+        description: "Bump the semantic version (major, minor, or patch). Updates pubspec.yaml and iOS project files. Resets iOS build to 1. Use when preparing a new release.",
+        schema: z.object({
+            type: z.enum(["major", "minor", "patch"]).describe("Version bump type"),
+        }),
+        handler: async (args) => {
+            await bumpVersion(args.type, true);
+            return `Version bumped (${args.type}).`;
+        },
+    },
+    {
+        name: "bump_ios_build",
+        description: "Increment only the iOS build number without changing the version. Use before uploading a new TestFlight build.",
+        schema: z.object({}),
+        handler: async () => {
+            await bumpIosBuildOnly(true);
+            return "iOS build number incremented.";
+        },
+    },
+    {
+        name: "bump_android_build",
+        description: "Increment only the Android build number without changing the version. Use before uploading to Google Play.",
+        schema: z.object({}),
+        handler: async () => {
+            await bumpAndroidBuildOnly(true);
+            return "Android build number incremented.";
+        },
+    },
+    {
+        name: "bump_both_builds",
+        description: "Increment both Android and iOS build numbers simultaneously without changing the version.",
+        schema: z.object({}),
+        handler: async () => {
+            await bumpBothBuilds(true);
+            return "Both build numbers incremented.";
+        },
+    },
+    {
+        name: "show_version",
+        description: "Display current version information including semver, Android build number, and iOS build number. Use to check project state before bumping or releasing.",
+        schema: z.object({}),
+        handler: async () => captureOutput(() => showCurrentVersion()),
+    },
+    {
+        name: "set_version",
+        description: "Manually set version and/or build numbers. Use when you need specific values rather than incrementing.",
+        schema: z.object({
+            appVersion: z.string().optional().describe("Version number to set (e.g. 2.0.0)"),
+            androidBuild: z.string().optional().describe("Android build number to set"),
+            iosBuild: z.string().optional().describe("iOS build number to set"),
+        }),
+        handler: async (args) => {
+            await updateFlutterVersion(args.appVersion ?? "", args.androidBuild ?? "", args.iosBuild ?? "");
+            return "Version updated.";
+        },
+    },
+    // ── Generate ──
+    {
+        name: "generate_module",
+        description: "Scaffold a complete BLoC module with bloc, event, state, screen, factory, and import files. Use when creating a new feature module in an Opticore project.",
+        schema: z.object({
+            moduleName: z.string().describe("Module name in snake_case (e.g. user_profile)"),
+            withRoute: z.boolean().optional().describe("Also register a route in app_router.dart"),
+        }),
+        handler: async (args) => {
+            const name = args.moduleName;
+            generateModule(name);
+            if (args.withRoute)
+                addRoute(name);
+            return `Module '${name}' generated.${args.withRoute ? " Route registered." : ""}`;
+        },
+    },
+    {
+        name: "generate_repo",
+        description: "Generate a repository file for an existing module. Use when adding data layer to a feature module.",
+        schema: z.object({
+            moduleName: z.string().describe("Module name in snake_case"),
+        }),
+        handler: async (args) => {
+            generateRepoModule(args.moduleName);
+            return `Repository generated for '${args.moduleName}'.`;
+        },
+    },
+    {
+        name: "add_route",
+        description: "Add a route entry for a module to app_router.dart. Use when a module exists but its route is not registered.",
+        schema: z.object({
+            moduleName: z.string().describe("Module name in snake_case"),
+        }),
+        handler: async (args) => {
+            addRoute(args.moduleName);
+            return `Route added for '${args.moduleName}'.`;
+        },
+    },
+    // ── Project ──
+    {
+        name: "open_xcode",
+        description: "Open the iOS project in Xcode.",
+        schema: z.object({}),
+        handler: async () => { await openIos(); return "Xcode opened."; },
+    },
+    {
+        name: "open_android_studio",
+        description: "Open the Android project in Android Studio.",
+        schema: z.object({}),
+        handler: async () => { await openAndroid(); return "Android Studio opened."; },
+    },
+    {
+        name: "list_devices",
+        description: "List all connected Flutter devices including emulators and physical devices. Use to see available devices before running the app.",
+        schema: z.object({
+            disableFvm: z.boolean().optional().describe("Use global Flutter SDK"),
+        }),
+        handler: async (args) => captureOutput(() => listDevices(!(args.disableFvm ?? false))),
+    },
+    {
+        name: "run_app",
+        description: "Run the Flutter app on a connected device. Use when the user wants to test the app.",
+        schema: z.object({
+            device: z.string().optional().describe("Device ID to run on"),
+            release: z.boolean().optional().describe("Run in release mode"),
+            flavor: z.string().optional().describe("Build flavor"),
+            disableFvm: z.boolean().optional().describe("Use global Flutter SDK"),
+        }),
+        handler: async (args) => {
+            await runApp({
+                device: args.device,
+                release: args.release ?? false,
+                flavor: args.flavor,
+                useFvm: !(args.disableFvm ?? false),
+            });
+            return "App running.";
+        },
+    },
+    {
+        name: "project_status",
+        description: "Show project version, config, platform info, and backup count. Use for a quick project overview.",
+        schema: z.object({}),
+        handler: async () => captureOutput(() => showStatus()),
+    },
+    {
+        name: "doctor",
+        description: "Check development environment health: Flutter SDK, FVM, CocoaPods, Xcode CLI tools, project structure. Use to diagnose setup issues or before starting work.",
+        schema: z.object({}),
+        handler: async () => captureOutput(() => runDoctor()),
+    },
+    // ── Config ──
+    {
+        name: "init",
+        description: "Initialize OptiKit configuration (.optikitrc.json) in the current project. Use when setting up OptiKit for the first time.",
+        schema: z.object({}),
+        handler: async () => { await initializeProject(); return "OptiKit initialized."; },
+    },
+    {
+        name: "init_app",
+        description: "Scaffold Opticore app structure (main.dart, config, router). Use when creating a new Opticore app from scratch.",
+        schema: z.object({
+            appName: z.string().optional().describe("App name for CoreSetup configuration"),
+        }),
+        handler: async (args) => {
+            await initOpticoreApp(args.appName ?? "MyApp");
+            return "Opticore app scaffolded.";
+        },
+    },
+    {
+        name: "rollback_list",
+        description: "List available OptiKit backups with timestamps. Use before restoring to see what backups exist.",
+        schema: z.object({
+            before: z.string().optional().describe("Filter backups before date (YYYY-MM-DD)"),
+        }),
+        handler: async (args) => captureOutput(() => rollbackFiles(args.before)),
+    },
+    {
+        name: "rollback_restore",
+        description: "Restore files from a specific OptiKit backup by index. Use to undo a version bump or other file modification.",
+        schema: z.object({
+            index: z.number().describe("Backup index number to restore"),
+        }),
+        handler: async (args) => {
+            await rollbackRestore(args.index);
+            return "Backup restored.";
+        },
+    },
+    {
+        name: "setup_vscode",
+        description: "Create .vscode/settings.json with Flutter/Dart settings including FVM SDK path and format-on-save.",
+        schema: z.object({}),
+        handler: async () => { await createVscodeSettings(); return "VS Code settings created."; },
+    },
+    {
+        name: "check_upgrade",
+        description: "Check if a newer version of OptiKit CLI is available on npm.",
+        schema: z.object({}),
+        handler: async () => captureOutput(() => checkUpgrade()),
+    },
+];

package/dist/commands/project/commands.js

@@ -0,0 +1,132 @@
+import { generateModule, generateRepoModule, addRoute } from "./generate.js";
+import { openIos, openAndroid, openIpaOutput, openBundleOutput, openApkOutput } from "./open.js";
+import { createVscodeSettings } from "./setup.js";
+import { listDevices, runApp, runAppInteractive } from "./devices.js";
+import { runDoctor } from "./doctor.js";
+import { showStatus } from "./status.js";
+export const projectCommands = [
+    {
+        command: "generate module <moduleName>",
+        aliases: ["gen module"],
+        describe: "Generate a module with structure",
+        builder: (yargs) => {
+            return yargs
+                .positional("moduleName", { describe: "The name of the module to generate", type: "string" })
+                .option("with-route", { alias: "r", type: "boolean", default: false, description: "Also register a route in app_router.dart" });
+        },
+        handler: (argv) => {
+            const moduleName = argv.moduleName;
+            generateModule(moduleName);
+            if (argv.withRoute) {
+                addRoute(moduleName);
+            }
+        },
+    },
+    {
+        command: "generate repo <moduleName>",
+        aliases: ["gen repo"],
+        describe: "Generate a repository file for an existing module",
+        builder: (yargs) => {
+            return yargs.positional("moduleName", { describe: "The module name", type: "string" });
+        },
+        handler: (argv) => { generateRepoModule(argv.moduleName); },
+    },
+    {
+        command: "add-route <moduleName>",
+        aliases: ["route"],
+        describe: "Add a route entry for a module to app_router.dart",
+        builder: (yargs) => {
+            return yargs.positional("moduleName", { describe: "The module name to add a route for", type: "string" });
+        },
+        handler: (argv) => { addRoute(argv.moduleName); },
+    },
+    {
+        command: "open-ios",
+        aliases: ["xcode"],
+        describe: "Open the iOS project in Xcode",
+        handler: async () => { await openIos(); },
+    },
+    {
+        command: "open-android",
+        aliases: ["studio"],
+        describe: "Open the Android project in Android Studio",
+        handler: async () => { await openAndroid(); },
+    },
+    {
+        command: "open-ipa",
+        describe: "Open the IPA build output directory",
+        handler: async () => { await openIpaOutput(); },
+    },
+    {
+        command: "open-apk",
+        describe: "Open the APK build output directory",
+        handler: async () => { await openApkOutput(); },
+    },
+    {
+        command: "open-bundle",
+        describe: "Open the Android Bundle build output directory",
+        handler: async () => { await openBundleOutput(); },
+    },
+    {
+        command: "setup-vscode",
+        aliases: ["vscode"],
+        describe: "Create a .vscode folder with recommended Flutter settings",
+        handler: async () => { await createVscodeSettings(); },
+    },
+    {
+        command: "devices",
+        aliases: ["devs"],
+        describe: "List all connected devices",
+        builder: {
+            "disable-fvm": { alias: "f", type: "boolean", default: false, description: "Run without FVM" },
+        },
+        handler: async (argv) => { await listDevices(!argv.disableFvm); },
+    },
+    {
+        command: "run",
+        describe: "Run Flutter app on connected device",
+        builder: {
+            device: { alias: "d", type: "string", description: "Specific device ID to run on" },
+            release: { alias: "r", type: "boolean", default: false, description: "Run in release mode" },
+            flavor: { type: "string", description: "Build flavor to use" },
+            "disable-fvm": { alias: "f", type: "boolean", default: false, description: "Run without FVM" },
+        },
+        handler: async (argv) => {
+            await runApp({
+                device: argv.device,
+                release: argv.release,
+                flavor: argv.flavor,
+                useFvm: !argv.disableFvm,
+            });
+        },
+    },
+    {
+        command: "run-select",
+        aliases: ["rs"],
+        describe: "Interactive device selection and run",
+        builder: {
+            release: { alias: "r", type: "boolean", default: false, description: "Run in release mode" },
+            flavor: { type: "string", description: "Build flavor to use" },
+            "disable-fvm": { alias: "f", type: "boolean", default: false, description: "Run without FVM" },
+        },
+        handler: async (argv) => {
+            await runAppInteractive({
+                release: argv.release,
+                flavor: argv.flavor,
+                useFvm: !argv.disableFvm,
+            });
+        },
+    },
+    {
+        command: "status",
+        aliases: ["info"],
+        describe: "Show project version, config, and platform info",
+        handler: async () => { await showStatus(); },
+    },
+    {
+        command: "doctor",
+        aliases: ["dr"],
+        describe: "Check development environment and project health",
+        handler: async () => { await runDoctor(); },
+    },
+];

package/dist/commands/project/devices.js

@@ -1,10 +1,8 @@
-import { exec } from "child_process";
-import { promisify } from "util";
-import { execCommand } from "../../utils/services/exec.js";
+import { execCommand, execCommandSilent } from "../../utils/services/exec.js";
 import { LoggerHelpers } from "../../utils/services/logger.js";
 import { validateFlutterProject, validateFlutterSdk } from "../../utils/validators/validation.js";
+import { handleCommandError } from "../../utils/helpers/error.js";
 import chalk from "chalk";
-const execAsync = promisify(exec);
 export { listDevices, runApp, getDevicesList, runAppInteractive };
 ;
 /**
@@ -13,7 +11,7 @@ export { listDevices, runApp, getDevicesList, runAppInteractive };
 async function getDevicesList(useFvm = false) {
     const flutterCommand = useFvm ? "fvm flutter" : "flutter";
     try {
-        const { stdout } = await execAsync(`${flutterCommand} devices --machine`);
+        const stdout = await execCommandSilent(`${flutterCommand} devices --machine`);
         const devices = JSON.parse(stdout);
         return devices.map(device => ({
             id: device.id,
@@ -68,13 +66,7 @@ async function listDevices(useFvm = false) {
         console.log(chalk.gray("═".repeat(60) + "\n"));
     }
     catch (error) {
-        if (error instanceof Error) {
-            LoggerHelpers.error(`Error listing devices: ${error.message}`);
-        }
-        else {
-            LoggerHelpers.error(`Error listing devices: ${error}`);
-        }
-        process.exit(1);
+        handleCommandError(error, "Error listing devices");
     }
 }
 /**
@@ -115,13 +107,7 @@ async function runApp(config) {
         await execCommand(command);
     }
     catch (error) {
-        if (error instanceof Error) {
-            LoggerHelpers.error(`Error running app: ${error.message}`);
-        }
-        else {
-            LoggerHelpers.error(`Error running app: ${error}`);
-        }
-        process.exit(1);
+        handleCommandError(error, "Error running app");
     }
 }
 /**
@@ -160,6 +146,10 @@ async function runAppInteractive(config) {
             input: process.stdin,
             output: process.stdout
         });
+        rl.on('error', () => {
+            LoggerHelpers.error("Input error. Please try again.");
+            process.exit(1);
+        });
         rl.question(chalk.yellow("Device number: "), async (answer) => {
             rl.close();
             const deviceIndex = parseInt(answer) - 1;
@@ -177,12 +167,6 @@ async function runAppInteractive(config) {
         });
     }
     catch (error) {
-        if (error instanceof Error) {
-            LoggerHelpers.error(`Error: ${error.message}`);
-        }
-        else {
-            LoggerHelpers.error(`Error: ${error}`);
-        }
-        process.exit(1);
+        handleCommandError(error, "Error selecting device");
     }
 }

package/dist/commands/project/doctor.js

@@ -0,0 +1,58 @@
+import chalk from "chalk";
+import { execCommandSilent } from "../../utils/services/exec.js";
+import { validateFlutterProject, validateIosProject, validateAndroidProject } from "../../utils/validators/validation.js";
+import { getConfigPath } from "../../utils/services/config.js";
+import { HELP_URLS } from "../../constants.js";
+import { sectionHeader } from "../../styles.js";
+export { runDoctor };
+async function checkCommand(name, command, fix) {
+    try {
+        const output = await execCommandSilent(command);
+        const version = output.trim().split("\n")[0];
+        return { name, passed: true, version };
+    }
+    catch {
+        return { name, passed: false, fix };
+    }
+}
+async function runDoctor() {
+    sectionHeader("OptiKit Doctor");
+    const results = [];
+    // Tool checks (run in parallel)
+    const toolChecks = await Promise.all([
+        checkCommand("Flutter SDK", "flutter --version", `Install Flutter: ${HELP_URLS.FLUTTER_INSTALL}`),
+        checkCommand("FVM", "fvm --version", `Install FVM: ${HELP_URLS.FVM_INSTALL} (optional)`),
+        checkCommand("CocoaPods", "pod --version", "Install: gem install cocoapods"),
+        checkCommand("Xcode CLI Tools", "xcode-select -p", "Install: xcode-select --install"),
+    ]);
+    results.push(...toolChecks);
+    // Project checks
+    results.push({ name: "Flutter project", passed: validateFlutterProject(true), fix: "Run from Flutter project root" }, { name: "iOS project", passed: validateIosProject(true), fix: "Run: flutter create ." }, { name: "Android project", passed: validateAndroidProject(true), fix: "Run: flutter create ." });
+    const configPath = getConfigPath();
+    results.push({
+        name: "OptiKit config",
+        passed: configPath !== null,
+        version: configPath ?? undefined,
+        fix: "Run: optikit init",
+    });
+    // Display results
+    console.log();
+    let passCount = 0;
+    for (const result of results) {
+        if (result.passed) {
+            passCount++;
+            const ver = result.version ? chalk.gray(` ${result.version}`) : "";
+            console.log(chalk.green("   ✔"), chalk.white(result.name) + ver);
+        }
+        else {
+            console.log(chalk.red("   ✖"), chalk.white(result.name));
+            if (result.fix) {
+                console.log(chalk.gray("     └─"), chalk.yellow(result.fix));
+            }
+        }
+    }
+    const total = results.length;
+    const color = passCount === total ? chalk.green : passCount >= total - 2 ? chalk.yellow : chalk.red;
+    console.log(chalk.gray("\n  ─────────────────────────────────"));
+    console.log(color(`  ${passCount}/${total} checks passed\n`));
+}