optikit 1.2.4 → 1.3.0

package/src/commands/clean/flutter.ts

@@ -3,7 +3,9 @@ import path from "path";
 import { execCommand } from "../../utils/services/exec.js";
 import { LoggerHelpers } from "../../utils/services/logger.js";
 import { validateFlutterProject, validateFlutterSdk } from "../../utils/validators/validation.js";
-import { createBackup } from "../../utils/services/backup.js";
+import { createBackupWithCleanup } from "../../utils/services/backup.js";
+import { handleCommandError } from "../../utils/helpers/error.js";
+import { getFlutterCommand } from "../../utils/services/command.js";
 
 export { cleanProject };
 
@@ -22,18 +24,18 @@ async function cleanProject(noFvm: boolean) {
   }
 
   try {
+    const useFvm = !noFvm;
+
     // Step 1: Run flutter clean
-    const flutterCommand = noFvm ? "flutter clean" : "fvm flutter clean";
     LoggerHelpers.info("Running Flutter clean...");
-    await execCommand(flutterCommand);
+    await execCommand(getFlutterCommand("flutter clean", useFvm));
     LoggerHelpers.success("Flutter clean completed.");
 
     // Step 2: Remove pubspec.lock using Node.js fs (cross-platform)
     const pubspecLockPath = path.join(process.cwd(), "pubspec.lock");
     if (fs.existsSync(pubspecLockPath)) {
       LoggerHelpers.info("Removing pubspec.lock...");
-      // Create backup before deletion
-      createBackup(pubspecLockPath);
+      createBackupWithCleanup(pubspecLockPath);
       fs.unlinkSync(pubspecLockPath);
       LoggerHelpers.success("pubspec.lock removed.");
     } else {
@@ -41,18 +43,12 @@ async function cleanProject(noFvm: boolean) {
     }
 
     // Step 3: Run flutter pub get
-    const pubGetCommand = noFvm ? "flutter pub get" : "fvm flutter pub get";
     LoggerHelpers.info("Running Flutter pub get...");
-    await execCommand(pubGetCommand);
+    await execCommand(getFlutterCommand("flutter pub get", useFvm));
     LoggerHelpers.success("Flutter pub get completed.");
 
     LoggerHelpers.success("Project cleaned successfully.");
   } catch (error) {
-    if (error instanceof Error) {
-      LoggerHelpers.error(`Error during clean: ${error.message}`);
-    } else {
-      LoggerHelpers.error(`Error during clean: ${error}`);
-    }
-    process.exit(1);
+    handleCommandError(error, "Error during clean");
   }
 }

package/src/commands/clean/ios.ts

@@ -3,6 +3,8 @@ import * as path from "path";
 import { LoggerHelpers } from "../../utils/services/logger.js";
 import { execInIos, execCommand, iosDirectory, execInIosWithRetry } from "../../utils/services/exec.js";
 import { validateFlutterProject, validateIosProject } from "../../utils/validators/validation.js";
+import { FLUTTER_COMMANDS, FVM_COMMANDS, RETRY_CONFIG } from "../../constants.js";
+import { handleCommandError } from "../../utils/helpers/error.js";
 
 export { cleanIosProject };
 
@@ -41,9 +43,14 @@ async function ensureFlutterArtifactsExist() {
   if (!fs.existsSync(flutterXcframeworkPath)) {
     LoggerHelpers.warning("Flutter.xcframework not found.");
 
+    const useFvm = fs.existsSync(path.join(process.cwd(), ".fvm", "flutter_sdk"));
+    const precacheCommand = useFvm
+      ? FVM_COMMANDS.PRECACHE_IOS
+      : FLUTTER_COMMANDS.PRECACHE_IOS;
+
     try {
       LoggerHelpers.info("Downloading Flutter.xcframework...");
-      await execCommand("fvm flutter precache --ios");
+      await execCommand(precacheCommand);
       LoggerHelpers.success(
         "Flutter.xcframework has been downloaded successfully."
       );
@@ -56,7 +63,7 @@ async function ensureFlutterArtifactsExist() {
     }
   } else {
     LoggerHelpers.success(
-      "Flutter.xcframework exists. No need to run 'fvm flutter precache --ios'."
+      "Flutter.xcframework exists. No need to run precache."
     );
   }
 }
@@ -98,7 +105,7 @@ async function cleanIosProject(cleanCache: boolean, repoUpdate: boolean) {
     if (repoUpdate) {
       LoggerHelpers.info("Updating CocoaPods repositories...");
       try {
-        await execInIosWithRetry("pod repo update", 3, 10000); 
+        await execInIosWithRetry("pod repo update", RETRY_CONFIG.DEFAULT_ATTEMPTS, RETRY_CONFIG.DEFAULT_DELAY_MS);
         LoggerHelpers.success("Updated CocoaPods repositories.");
       } catch (error) {
         LoggerHelpers.error("Failed to update CocoaPods repositories. Retrying...");
@@ -106,24 +113,17 @@ async function cleanIosProject(cleanCache: boolean, repoUpdate: boolean) {
 
       LoggerHelpers.info("Installing pods with repo update...");
       try {
-        await execInIosWithRetry("pod update", 3, 10000); 
+        await execInIosWithRetry("pod update", RETRY_CONFIG.DEFAULT_ATTEMPTS, RETRY_CONFIG.DEFAULT_DELAY_MS);
         LoggerHelpers.success("Installed pods with repo update.");
       } catch (error) {
         LoggerHelpers.error("Failed to update pods. Retrying...");
       }
     } else {
       LoggerHelpers.info("Installing pods without repo update...");
-      await execInIosWithRetry("pod install", 3, 10000);
+      await execInIosWithRetry("pod install", RETRY_CONFIG.DEFAULT_ATTEMPTS, RETRY_CONFIG.DEFAULT_DELAY_MS);
       LoggerHelpers.success("Installed pods without repo update.");
     }
   } catch (error) {
-    if (error instanceof Error) {
-      LoggerHelpers.error(`Error: ${error.message}`);
-    } else if (typeof error === "string") {
-      LoggerHelpers.error(`Error: ${error}`);
-    } else {
-      LoggerHelpers.error(`Unknown error: ${JSON.stringify(error)}`);
-    }
-    process.exit(1);
+    handleCommandError(error, "Error cleaning iOS project");
   }
 }

package/src/commands/config/aliases.ts

@@ -0,0 +1,150 @@
+import chalk from "chalk";
+
+interface AliasEntry {
+  alias: string;
+  command: string;
+  description: string;
+}
+
+interface FlagEntry {
+  short: string;
+  long: string;
+  commands: string;
+}
+
+const buildAliases: AliasEntry[] = [
+  { alias: "apk", command: "flutter-build-apk", description: "Build release APK" },
+  { alias: "aab", command: "flutter-build-bundle", description: "Build release AAB bundle" },
+  { alias: "ios", command: "flutter-build-ios", description: "Build iOS app" },
+  { alias: "ipa", command: "flutter-build-ipa", description: "Build release IPA" },
+  { alias: "tf", command: "testflight", description: "Bump iOS + build IPA" },
+];
+
+const cleanAliases: AliasEntry[] = [
+  { alias: "c", command: "clean", description: "Clean Flutter (use -a for all)" },
+  { alias: "cf", command: "clean-flutter", description: "Clean Flutter project" },
+  { alias: "ci", command: "clean-ios", description: "Clean iOS / CocoaPods" },
+];
+
+const versionAliases: AliasEntry[] = [
+  { alias: "v", command: "version", description: "Show current version" },
+  { alias: "bi", command: "bump-ios", description: "Bump iOS build number" },
+  { alias: "ba", command: "bump-android", description: "Bump Android build number" },
+  { alias: "bb", command: "bump-build", description: "Bump both build numbers" },
+  { alias: "vset", command: "flutter-update-version", description: "Set version manually" },
+];
+
+const projectAliases: AliasEntry[] = [
+  { alias: "gen", command: "generate", description: "Generate module or repo" },
+  { alias: "route", command: "add-route", description: "Add route to app_router.dart" },
+  { alias: "devs", command: "devices", description: "List connected devices" },
+  { alias: "rs", command: "run-select", description: "Interactive device select & run" },
+  { alias: "info", command: "status", description: "Project status snapshot" },
+  { alias: "dr", command: "doctor", description: "Check environment health" },
+];
+
+const openAliases: AliasEntry[] = [
+  { alias: "xcode", command: "open-ios", description: "Open project in Xcode" },
+  { alias: "studio", command: "open-android", description: "Open project in Android Studio" },
+];
+
+const configAliases: AliasEntry[] = [
+  { alias: "vscode", command: "setup-vscode", description: "Setup VS Code settings" },
+  { alias: "undo", command: "rollback", description: "List/restore backups" },
+  { alias: "up", command: "upgrade", description: "Check for CLI updates" },
+];
+
+const shortFlags: FlagEntry[] = [
+  { short: "-f", long: "--disable-fvm", commands: "build, clean, run, devs" },
+  { short: "-a", long: "--all", commands: "clean (flutter + iOS)" },
+  { short: "-i", long: "--ios", commands: "clean (also clean iOS)" },
+  { short: "-c", long: "--clean-cache", commands: "clean-ios" },
+  { short: "-u", long: "--repo-update", commands: "clean-ios" },
+  { short: "-r", long: "--with-route", commands: "gen module" },
+  { short: "-y", long: "--yes", commands: "bump commands" },
+  { short: "-r", long: "--release", commands: "run, run-select" },
+  { short: "-d", long: "--device", commands: "run" },
+];
+
+const comboFlags: FlagEntry[] = [
+  { short: "--clean", long: "", commands: "apk, aab, ios, ipa  Clean before building" },
+  { short: "-o", long: "--open", commands: "apk, aab, ipa, tf   Open output after build" },
+  { short: "-b", long: "--bump", commands: "apk, aab, ios, ipa  Bump version before build" },
+  { short: "-i", long: "--bump-ios", commands: "ipa             Bump iOS build before build" },
+];
+
+function printGroup(title: string, entries: AliasEntry[]): void {
+  console.log(chalk.cyan.bold(`\n  ${title}`));
+  console.log(chalk.gray(`  ${"─".repeat(title.length + 4)}`));
+  for (const { alias, command, description } of entries) {
+    const aliasCol = chalk.white.bold(alias.padEnd(10));
+    const cmdCol = chalk.gray(command.padEnd(24));
+    const descCol = chalk.gray(description);
+    console.log(`    ${aliasCol} ${cmdCol} ${descCol}`);
+  }
+}
+
+function printFlags(title: string, flags: FlagEntry[]): void {
+  console.log(chalk.cyan.bold(`\n  ${title}`));
+  console.log(chalk.gray(`  ${"─".repeat(title.length + 4)}`));
+  for (const { short: s, long: l, commands } of flags) {
+    const shortCol = chalk.white.bold(s.padEnd(8));
+    const longCol = l ? chalk.gray(l.padEnd(16)) : "".padEnd(16);
+    const cmdCol = chalk.gray(commands);
+    console.log(`    ${shortCol} ${longCol} ${cmdCol}`);
+  }
+}
+
+function printExamples(): void {
+  console.log(chalk.cyan.bold("\n  Common Workflows"));
+  console.log(chalk.gray(`  ${"─".repeat(22)}`));
+
+  const examples = [
+    ["ok apk", "Build release APK"],
+    ["ok apk --clean", "Clean + build APK"],
+    ["ok apk -b patch -o", "Bump patch + build APK + open"],
+    ["ok ipa --clean -o", "Clean + build IPA + open"],
+    ["ok ipa -i -o", "Bump iOS + build IPA + open"],
+    ["ok tf", "TestFlight (bump iOS + build IPA)"],
+    ["ok tf -o", "TestFlight + open output"],
+    ["", ""],
+    ["ok c -a", "Clean Flutter + iOS"],
+    ["ok ci -cu", "Clean iOS: cache + repo update"],
+    ["ok bump patch", "Bump patch version"],
+    ["ok gen module login -r", "Generate module with auto-route"],
+    ["ok rs -r", "Run on selected device (release)"],
+  ];
+
+  for (const [cmd, desc] of examples) {
+    if (!cmd) {
+      console.log();
+      continue;
+    }
+    console.log(`    ${chalk.green(cmd.padEnd(28))} ${chalk.gray(desc)}`);
+  }
+}
+
+function printSetupTip(): void {
+  console.log(chalk.cyan.bold("\n  Usage"));
+  console.log(chalk.gray(`  ${"─".repeat(9)}`));
+  console.log(chalk.gray("    Use ") + chalk.white.bold("ok") + chalk.gray(" or ") + chalk.white.bold("optikit") + chalk.gray(" — both work identically."));
+  console.log(chalk.gray("\n    Enable tab completion:"));
+  console.log(chalk.white.bold("    ok completion >> ~/.zshrc"));
+  console.log();
+}
+
+export function showAliases(): void {
+  console.log(chalk.cyan.bold("\n  OptiKit Alias Reference"));
+  console.log(chalk.gray("  ═══════════════════════════"));
+
+  printGroup("Build", buildAliases);
+  printGroup("Clean", cleanAliases);
+  printGroup("Version & Bump", versionAliases);
+  printGroup("Project", projectAliases);
+  printGroup("Open", openAliases);
+  printGroup("Config", configAliases);
+  printFlags("Short Flags", shortFlags);
+  printFlags("Build Combo Flags", comboFlags);
+  printExamples();
+  printSetupTip();
+}

package/src/commands/config/commands.ts

@@ -0,0 +1,50 @@
+import type { CommandModule } from "yargs";
+import { initializeProject } from "./init.js";
+import { initOpticoreApp } from "./initApp.js";
+import { rollbackFiles, rollbackRestore } from "./rollback.js";
+import { checkUpgrade } from "./upgrade.js";
+import { showAliases } from "./aliases.js";
+
+export const configCommands: CommandModule[] = [
+  {
+    command: "init",
+    describe: "Initialize OptiKit configuration in the current project",
+    handler: async () => { await initializeProject(); },
+  },
+  {
+    command: "init-app",
+    describe: "Scaffold Opticore app structure (main.dart, config, router)",
+    builder: {
+      "app-name": { type: "string", default: "MyApp", description: "The app name for CoreSetup configuration" },
+    },
+    handler: async (argv) => { await initOpticoreApp(argv.appName as string); },
+  },
+  {
+    command: "rollback",
+    aliases: ["undo"],
+    describe: "List and restore files from OptiKit backups",
+    builder: {
+      restore: { type: "number", description: "Restore backup by index number" },
+      before: { type: "string", description: "Show backups before date (YYYY-MM-DD)" },
+    },
+    handler: async (argv) => {
+      const restoreIndex = argv.restore as number | undefined;
+      if (restoreIndex !== undefined) {
+        await rollbackRestore(restoreIndex);
+      } else {
+        await rollbackFiles(argv.before as string | undefined);
+      }
+    },
+  },
+  {
+    command: "upgrade",
+    aliases: ["up"],
+    describe: "Check for OptiKit CLI updates",
+    handler: async () => { await checkUpgrade(); },
+  },
+  {
+    command: "aliases",
+    describe: "Show all command aliases, short flags, and examples",
+    handler: () => { showAliases(); },
+  },
+];

package/src/commands/config/initApp.ts

@@ -0,0 +1,213 @@
+import fs from "fs";
+import path from "path";
+import { LoggerHelpers } from "../../utils/services/logger.js";
+import { validateFlutterProject } from "../../utils/validators/validation.js";
+import { handleCommandError } from "../../utils/helpers/error.js";
+import { writeFile, createDirectories } from "../../utils/helpers/file.js";
+
+export { initOpticoreApp };
+
+async function initOpticoreApp(appName: string): Promise<void> {
+  if (!validateFlutterProject()) {
+    process.exit(1);
+  }
+
+  try {
+    const libDir = path.join(process.cwd(), "lib");
+    const configDir = path.join(libDir, "config");
+
+    // Create config directory
+    createDirectories(configDir, []);
+    if (!fs.existsSync(configDir)) {
+      fs.mkdirSync(configDir, { recursive: true });
+    }
+
+    LoggerHelpers.info(`Initializing Opticore app: ${appName}...`);
+
+    // 1. Generate main.dart
+    generateMainDart(libDir, appName);
+
+    // 2. Generate app_router.dart
+    generateAppRouter(configDir);
+
+    // 3. Generate app_config_setup.dart
+    generateAppConfigSetup(configDir, appName);
+
+    // 4. Generate network_setup.dart
+    generateNetworkSetup(configDir);
+
+    LoggerHelpers.success(`Opticore app "${appName}" initialized successfully.`);
+    LoggerHelpers.info("\nGenerated files:");
+    LoggerHelpers.info("  lib/main.dart");
+    LoggerHelpers.info("  lib/config/app_router.dart");
+    LoggerHelpers.info("  lib/config/app_config_setup.dart");
+    LoggerHelpers.info("  lib/config/network_setup.dart");
+    LoggerHelpers.info("\nNext steps:");
+    LoggerHelpers.info("  1. Review and customize lib/config/app_config_setup.dart");
+    LoggerHelpers.info("  2. Add routes in lib/config/app_router.dart");
+    LoggerHelpers.info("  3. Generate modules with: optikit generate module <name>");
+    LoggerHelpers.info("  4. Register routes with: optikit add-route <name>");
+  } catch (error) {
+    handleCommandError(error, "Error initializing Opticore app");
+  }
+}
+
+function generateMainDart(libDir: string, appName: string) {
+  const mainPath = path.join(libDir, "main.dart");
+
+  if (fs.existsSync(mainPath)) {
+    LoggerHelpers.warning("main.dart already exists. Skipping to avoid overwrite.");
+    LoggerHelpers.info("To regenerate, delete lib/main.dart first.");
+    return;
+  }
+
+  const template = `import 'package:flutter/material.dart';
+import 'package:opticore/opticore.dart';
+import 'config/app_config_setup.dart';
+import 'config/app_router.dart';
+import 'config/network_setup.dart';
+
+void main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+
+  runApp(
+    CoreSetup(
+      appConfig: AppConfig(
+        appTitle: '${appName}',
+        theme: AppConfigSetup.theme,
+        initialRoute: AppRouter.initialRoute,
+        onGenerateRoute: AppRouter.generateRoute,
+      ),
+      prepConfig: () async {
+        await NetworkSetup.initialize();
+        // Add other initialization here (Firebase, Hive, etc.)
+      },
+    ),
+  );
+}
+`;
+
+  writeFile(mainPath, template);
+  LoggerHelpers.success("Created lib/main.dart");
+}
+
+function generateAppRouter(configDir: string) {
+  const routerPath = path.join(configDir, "app_router.dart");
+
+  const template = `import 'package:flutter/material.dart';
+import 'package:opticore/opticore.dart';
+
+class AppRouter {
+  static const String initialRoute = '/';
+
+  static Route<dynamic> generateRoute(RouteSettings settings) {
+    switch (settings.name) {
+      // Routes will be added here by: optikit add-route <moduleName>
+      // === OPTIKIT_ROUTE_ANCHOR === (do not remove this line)
+      default:
+        return MaterialPageRoute(
+          builder: (_) => Scaffold(
+            body: Center(
+              child: Text('No route defined for \${settings.name}'),
+            ),
+          ),
+        );
+    }
+  }
+}
+`;
+
+  writeFile(routerPath, template);
+  LoggerHelpers.success("Created lib/config/app_router.dart");
+}
+
+function generateAppConfigSetup(configDir: string, appName: string) {
+  const configPath = path.join(configDir, "app_config_setup.dart");
+
+  const template = `import 'package:flutter/material.dart';
+import 'package:opticore/opticore.dart';
+
+class AppConfigSetup {
+  static ThemeData get theme => ThemeData(
+    colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
+    useMaterial3: true,
+  );
+
+  static void initializeConfigs() {
+    // Toast notification colors
+    ToastConfig.instantiate(
+      const ToastConfig(
+        successColor: Colors.green,
+        errorColor: Colors.red,
+        infoColor: Colors.blue,
+        warningColor: Colors.orange,
+      ),
+    );
+
+    // API response messages
+    ApiResponseConfig.instantiate(
+      ApiResponseConfig(
+        errorMessage: 'Something went wrong. Please try again.',
+        requestTimeoutMessage: 'Request timed out. Check your connection.',
+        networkIssuesMessage: 'Network error. Please check your internet.',
+      ),
+    );
+
+    // Unauthenticated handler (401/403)
+    UnAuthenticatedConfig.instantiate(
+      UnAuthenticatedConfig(
+        onUnauthenticated: () {
+          // Clear user cache and navigate to login
+          // Example: RouteHelper.pushAndRemoveUntil(LoginScreen());
+        },
+      ),
+    );
+  }
+}
+`;
+
+  writeFile(configPath, template);
+  LoggerHelpers.success("Created lib/config/app_config_setup.dart");
+}
+
+function generateNetworkSetup(configDir: string) {
+  const networkPath = path.join(configDir, "network_setup.dart");
+
+  const template = `import 'package:opticore/opticore.dart';
+
+class NetworkSetup {
+  static const String baseUrl = 'https://api.example.com';
+
+  static Future<void> initialize() async {
+    // Configure base URL
+    NetworkHelper.instance.setBaseUrl(baseUrl);
+
+    // Set default headers
+    await NetworkConfig.updateHeaders(
+      newHeaders: {
+        'Content-Type': 'application/json',
+        'Accept': 'application/json',
+      },
+    );
+
+    // Optional: Enable SSL certificate pinning
+    // await NetworkHelper.loadPinningCertificate();
+  }
+
+  static Future<void> setAuthToken(String token) async {
+    await NetworkConfig.updateHeaders(
+      newHeaders: {
+        'Authorization': 'Bearer \$token',
+      },
+    );
+  }
+
+  static Future<void> clearAuthToken() async {
+    await NetworkConfig.removeHeaders(keys: ['Authorization']);
+  }
+}
+`;
+
+  writeFile(networkPath, template);
+  LoggerHelpers.success("Created lib/config/network_setup.dart");
+}

package/src/commands/config/rollback.ts

@@ -4,16 +4,28 @@ import { LoggerHelpers } from "../../utils/services/logger.js";
 import { restoreBackup } from "../../utils/services/backup.js";
 import chalk from "chalk";
 
-export { rollbackFiles };
+export { rollbackFiles, rollbackRestore };
 
 /**
  * Lists all available backups and allows restoration
  */
-async function rollbackFiles(): Promise<void> {
+async function rollbackFiles(beforeDate?: string): Promise<void> {
   try {
     LoggerHelpers.info("Searching for OptiKit backups...");
 
-    const backups = findAllBackups(process.cwd());
+    let backups = findAllBackups(process.cwd());
+
+    // Filter by date if --before is provided
+    if (beforeDate) {
+      const cutoff = new Date(beforeDate);
+      if (isNaN(cutoff.getTime())) {
+        LoggerHelpers.error(`Invalid date format: ${beforeDate}. Use YYYY-MM-DD.`);
+        process.exit(1);
+      }
+      cutoff.setHours(23, 59, 59, 999);
+      backups = backups.filter((b) => b.timestamp <= cutoff);
+      LoggerHelpers.info(`Filtering backups before ${beforeDate}...`);
+    }
 
     if (backups.length === 0) {
       LoggerHelpers.warning("No backups found in this project.");
@@ -94,7 +106,7 @@ async function rollbackFiles(): Promise<void> {
 /**
  * Restores a specific backup by index
  */
-export async function rollbackRestore(index: number): Promise<void> {
+async function rollbackRestore(index: number): Promise<void> {
   try {
     const backups = findAllBackups(process.cwd());
 

package/src/commands/config/upgrade.ts

@@ -0,0 +1,40 @@
+import chalk from "chalk";
+import { execCommandSilent } from "../../utils/services/exec.js";
+import { LoggerHelpers } from "../../utils/services/logger.js";
+import { createRequire } from "module";
+
+const require = createRequire(import.meta.url);
+
+export { checkUpgrade };
+
+async function checkUpgrade(): Promise<void> {
+  try {
+    const packageInfo: { version: string } = require("../../../package.json");
+    const currentVersion = packageInfo.version;
+
+    LoggerHelpers.info("Checking for updates...");
+
+    let latestVersion: string;
+    try {
+      const output = await execCommandSilent("npm view optikit version");
+      latestVersion = output.trim();
+    } catch {
+      LoggerHelpers.warning("Could not check npm registry. Are you online?");
+      console.log(chalk.cyan("\n  Current:"), chalk.white(currentVersion));
+      return;
+    }
+
+    console.log(chalk.bold("\nOptiKit Version Check\n"));
+    console.log(chalk.cyan("  Current:"), chalk.white(currentVersion));
+    console.log(chalk.cyan("  Latest: "), chalk.white(latestVersion));
+
+    if (currentVersion === latestVersion) {
+      console.log(chalk.green("\n  You're up to date!\n"));
+    } else {
+      console.log(chalk.yellow(`\n  Update available: ${currentVersion} → ${latestVersion}`));
+      console.log(chalk.white("  Run:"), chalk.cyan("npm install -g optikit\n"));
+    }
+  } catch (error) {
+    LoggerHelpers.error(`Error checking for updates: ${error instanceof Error ? error.message : error}`);
+  }
+}

package/src/commands/mcp/commands.ts

@@ -0,0 +1,23 @@
+import type { CommandModule } from "yargs";
+import { startMcpServer } from "./server.js";
+import { setupClaude } from "./setup.js";
+
+export const mcpCommands: CommandModule[] = [
+  {
+    command: "mcp",
+    describe: "Start OptiKit MCP server for Claude Code integration",
+    handler: async () => { await startMcpServer(); },
+  },
+  {
+    command: "setup-claude",
+    describe: "Register OptiKit MCP server with Claude Code",
+    builder: {
+      uninstall: {
+        type: "boolean",
+        default: false,
+        description: "Remove OptiKit MCP server from Claude Code",
+      },
+    },
+    handler: (argv) => { setupClaude(argv.uninstall as boolean); },
+  },
+];

package/src/commands/mcp/server.ts

@@ -0,0 +1,35 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createRequire } from "module";
+import { MCP_CONFIG } from "../../constants.js";
+import { tools } from "./tools.js";
+
+const require = createRequire(import.meta.url);
+const packageInfo: { version: string } = require("../../../package.json");
+
+export async function startMcpServer(): Promise<void> {
+  const server = new McpServer({
+    name: MCP_CONFIG.SERVER_NAME,
+    version: packageInfo.version,
+  });
+
+  for (const tool of tools) {
+    server.tool(
+      tool.name,
+      tool.description,
+      { ...tool.schema.shape },
+      async (args) => {
+        try {
+          const result = await tool.handler(args as Record<string, unknown>);
+          return { content: [{ type: "text" as const, text: result }] };
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          return { content: [{ type: "text" as const, text: `Error: ${message}` }], isError: true };
+        }
+      },
+    );
+  }
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}