optikit 1.2.5 → 1.3.0

package/.claude/commands/build.md

@@ -0,0 +1,57 @@
+# OptiKit Build
+
+Build a production Flutter artifact for this project using the OptiKit CLI.
+
+## Available Builds
+
+| Artifact | Command | Platform | Flags |
+|---|---|---|---|
+| APK | `optikit flutter-build-apk` | Android | `--release --obfuscate --split-debug-info` |
+| AAB (Bundle) | `optikit flutter-build-bundle` | Android (Play Store) | `--release --obfuscate --split-debug-info` |
+| iOS app | `optikit flutter-build-ios` | iOS (no archive) | `--release` |
+| IPA | `optikit flutter-build-ipa` | iOS (App Store / TestFlight) | `--release` |
+
+All commands use FVM by default. Add `--disable-fvm` if the project doesn't use FVM.
+
+## Build Output Locations
+
+| Artifact | Path |
+|---|---|
+| APK | `build/app/outputs/flutter-apk/` |
+| AAB | `build/app/outputs/bundle/release/` |
+| IPA | `build/ios/ipa/` |
+
+## Open Output in Finder After Build
+
+```bash
+optikit open-apk     # open APK output folder
+optikit open-bundle  # open AAB output folder
+optikit open-ipa     # open IPA output folder
+```
+
+## Typical Release Workflow
+
+```bash
+# 1. Bump version first
+optikit bump patch
+
+# 2. Build
+optikit flutter-build-ipa     # for iOS
+optikit flutter-build-bundle  # for Android
+
+# 3. Open output to upload
+optikit open-ipa
+optikit open-bundle
+```
+
+## Pre-flight Checks (Automatic)
+
+Before building, OptiKit validates:
+- `pubspec.yaml` exists (Flutter project check)
+- Flutter or FVM SDK is installed
+- `ios/` with `Runner.xcodeproj` or `.xcworkspace` (iOS builds)
+- `android/` with `build.gradle` (Android builds)
+
+---
+
+Now look at the user's request and run the appropriate build command(s) above.

package/.claude/commands/clean.md

@@ -0,0 +1,45 @@
+# OptiKit Clean
+
+Clean the Flutter or iOS project using the OptiKit CLI.
+
+## Flutter Clean
+
+Runs 3 steps in sequence: `flutter clean` → backup + delete `pubspec.lock` → `flutter pub get`
+
+```bash
+optikit clean-flutter             # with FVM (default)
+optikit clean-flutter --disable-fvm  # without FVM
+```
+
+## iOS Clean (CocoaPods)
+
+All pod operations run inside `ios/`, with **3 retries and 10s delay** per network operation.
+OptiKit also auto-runs `flutter precache --ios` if `Flutter.xcframework` is missing.
+
+| Command | Steps |
+|---|---|
+| `optikit clean-ios` | deintegrate → pod install |
+| `optikit clean-ios --clean-cache` | deintegrate → pod cache clean → pod install |
+| `optikit clean-ios --repo-update` | deintegrate → pod repo update → pod update |
+| `optikit clean-ios --clean-cache --repo-update` | full nuclear clean |
+
+## When to Use What
+
+| Symptom | Solution |
+|---|---|
+| Weird build errors, stale cache | `optikit clean-flutter` |
+| Pod version conflicts | `optikit clean-ios` |
+| CocoaPods cache corrupt | `optikit clean-ios --clean-cache` |
+| Outdated pod specs / repo issues | `optikit clean-ios --repo-update` |
+| Everything broken after dependency update | `optikit clean-flutter` + `optikit clean-ios --clean-cache --repo-update` |
+
+## Full Nuclear Clean
+
+```bash
+optikit clean-flutter
+optikit clean-ios --clean-cache --repo-update
+```
+
+---
+
+Now look at the user's request and run the appropriate clean command(s) above.

package/.claude/commands/generate.md

@@ -0,0 +1,64 @@
+# OptiKit Generate Module
+
+Scaffold a complete BLoC pattern module for the Opticore framework using the OptiKit CLI.
+
+> Only for projects using the [Opticore](https://pub.dev/packages/opticore) package.
+
+## Command
+
+```bash
+optikit generate module <module_name>
+```
+
+**Name rules:** `snake_case` only — lowercase letters, numbers, underscores. No hyphens, no spaces, no uppercase.
+
+## What Gets Generated
+
+Running `optikit generate module user_profile` creates:
+
+```
+lib/module/user_profile/
+├── import/   user_profile_import.dart   ← central hub (imports flutter + opticore, declares all parts)
+├── bloc/     user_profile_bloc.dart     ← UserProfileBloc extends BaseBloc
+├── event/    user_profile_event.dart    ← UserProfileInitialEvent extends BaseEvent
+├── state/    user_profile_state.dart    ← UserProfileInitialState extends RenderDataState
+├── screen/   user_profile_screen.dart   ← UserProfileScreen extends StatefulWidget + BaseScreen
+└── factory/  user_profile_factory.dart  ← UserProfileStateFactory extends BaseFactory
+```
+
+## Class Naming
+
+`user_profile` → prefix `UserProfile` (snake_case → PascalCase, no suffix on prefix):
+
+| File | Class |
+|---|---|
+| `user_profile_bloc.dart` | `UserProfileBloc` |
+| `user_profile_event.dart` | `UserProfileInitialEvent` |
+| `user_profile_state.dart` | `UserProfileInitialState` |
+| `user_profile_screen.dart` | `UserProfileScreen` |
+| `user_profile_factory.dart` | `UserProfileStateFactory` |
+
+## Generated Import File
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:opticore/opticore.dart';
+
+part '../bloc/user_profile_bloc.dart';
+part '../event/user_profile_event.dart';
+part '../screen/user_profile_screen.dart';
+part '../state/user_profile_state.dart';
+part '../factory/user_profile_factory.dart';
+```
+
+All other files start with `part of '../import/user_profile_import.dart';`
+
+## After Generation
+
+Wire the new screen into your router. The module is fully self-contained via the `part of` system — just import `user_profile_import.dart` where you need access to the screen or bloc.
+
+> If the module already exists, files are overwritten without stopping — OptiKit shows a warning but continues.
+
+---
+
+Now look at the user's request, determine the module name in snake_case, and run the command above.

package/.claude/commands/rollback.md

@@ -0,0 +1,67 @@
+# OptiKit Rollback
+
+Inspect and restore automatic OptiKit backups for this Flutter project.
+
+## How Backups Work
+
+OptiKit automatically backs up files before modifying them:
+
+| Command | Files Backed Up |
+|---|---|
+| `bump patch/minor/major` | `pubspec.yaml`, `project.pbxproj`, `Info.plist` |
+| `bump-ios`, `bump-android`, `bump-build` | `pubspec.yaml`, `project.pbxproj`, `Info.plist` |
+| `flutter-update-version` | `pubspec.yaml`, `project.pbxproj`, `Info.plist` |
+| `clean-flutter` | `pubspec.lock` |
+
+Backups live in `.optikit-backup/` next to each original file. Last 5 kept per file.
+
+## List All Backups
+
+```bash
+optikit rollback
+```
+
+Output is grouped by original file, sorted newest first, with timestamps and sizes:
+
+```
+pubspec.yaml
+  [1] 12/23/2025, 10:30:00 AM (5m ago, 2.14 KB)
+  [2] 12/23/2025, 9:15:00 AM (1h ago, 2.13 KB)
+
+ios/Runner.xcodeproj/project.pbxproj
+  [3] 12/23/2025, 10:30:00 AM (5m ago, 48.2 KB)
+```
+
+## Restore a Specific Backup
+
+```bash
+optikit rollback --restore <number>
+```
+
+Example — restore the most recent pubspec.yaml backup:
+
+```bash
+optikit rollback --restore 1
+```
+
+## Backup File Structure
+
+```
+your-flutter-project/
+├── pubspec.yaml
+├── .optikit-backup/
+│   └── pubspec_2025-12-23T10-30-00-000Z.yaml
+└── ios/
+    ├── Runner.xcodeproj/
+    │   └── .optikit-backup/
+    │       └── project_2025-12-23T10-30-00-000Z.pbxproj
+    └── Runner/
+        └── .optikit-backup/
+            └── Info_2025-12-23T10-30-00-000Z.plist
+```
+
+> `.optikit-backup/` is gitignored automatically by `optikit init`.
+
+---
+
+Now look at the user's request — list backups or restore the one they need.

package/.claude/commands/run.md

@@ -0,0 +1,63 @@
+# OptiKit Run & Devices
+
+List connected devices and run the Flutter app using the OptiKit CLI.
+
+## List Connected Devices
+
+```bash
+optikit devices               # with FVM (default)
+optikit devices --disable-fvm
+```
+
+Shows: device number, name, platform, `[Emulator]` or `[Physical]`, and device ID.
+
+## Run the App
+
+### On Default Device
+
+```bash
+optikit run
+optikit run --release          # release mode (-r)
+optikit run --flavor <name>    # with flavor (-f)
+optikit run --disable-fvm
+```
+
+### On a Specific Device
+
+```bash
+# First list devices to get the ID
+optikit devices
+
+# Then run on that device
+optikit run --device <device-id>    # or -d <device-id>
+optikit run -d <device-id> --release
+optikit run -d <device-id> --flavor <name>
+```
+
+### Interactive Device Picker
+
+Prompts for a numbered selection from the connected devices list:
+
+```bash
+optikit run-select
+optikit run-select --release
+optikit run-select --flavor <name>
+optikit run-select --disable-fvm
+```
+
+## Typical Workflow
+
+```bash
+# See what's connected
+optikit devices
+
+# Pick interactively
+optikit run-select
+
+# Or target a specific device
+optikit run -d emulator-5554
+```
+
+---
+
+Now look at the user's request and run the appropriate device/run command(s) above.

package/.claude/commands/setup.md

@@ -0,0 +1,69 @@
+# OptiKit Setup
+
+Initialize OptiKit and configure the development environment for this Flutter project.
+
+## Initialize OptiKit
+
+Run once per project to create the config file and update `.gitignore`:
+
+```bash
+optikit init
+```
+
+Creates `.optikitrc.json`:
+
+```json
+{
+  "backupRetentionCount": 5,
+  "useFvmByDefault": true,
+  "autoBackup": true,
+  "verbose": false
+}
+```
+
+Also appends `.optikit-backup/` to `.gitignore` automatically.
+If config already exists, it warns and exits without overwriting.
+
+## Configure VSCode for FVM
+
+Creates `.vscode/settings.json` with Flutter/FVM settings:
+
+```bash
+optikit setup-vscode
+```
+
+Generated settings:
+
+```json
+{
+  "dart.flutterSdkPath": ".fvm/flutter_sdk",
+  "editor.formatOnSave": true,
+  "dart.previewFlutterUiGuides": true,
+  "files.exclude": {
+    "**/.git": true,
+    "**/.DS_Store": true,
+    "**/node_modules": true,
+    "**/build": true
+  }
+}
+```
+
+## Open IDE Projects
+
+```bash
+optikit open-ios      # open ios/Runner.xcworkspace in Xcode
+optikit open-android  # open android/ in Android Studio
+```
+
+## Full Onboarding for a New Developer
+
+```bash
+optikit init           # config + .gitignore
+optikit setup-vscode   # VSCode settings
+optikit open-ios       # verify iOS project opens in Xcode
+optikit open-android   # verify Android project opens in Android Studio
+```
+
+---
+
+Now look at the user's request and run the appropriate setup command(s) above.

package/.claude/commands/sync-docs.md

@@ -0,0 +1,148 @@
+# Sync OptiKit Documentation
+
+You are the documentation maintainer for the OptiKit CLI project. Your job is to keep all documentation perfectly in sync with the actual source code after any change.
+
+Run this workflow whenever:
+- A new command is added or removed
+- A command's flags, behavior, or output changes
+- A new utility, service, or helper is added
+- File structure changes
+- Version bump logic changes
+- Any source file in `src/` is modified
+
+---
+
+## Step 1 — Read the Source of Truth
+
+Read these files to understand the current state of the code:
+
+```
+src/cli.ts                          ← all commands and their flags
+src/constants.ts                    ← build flags, paths, retry config, error messages
+src/commands/build/releases.ts      ← build command implementations
+src/commands/clean/flutter.ts       ← flutter clean steps
+src/commands/clean/ios.ts           ← ios clean steps + retry logic
+src/commands/version/bump.ts        ← bump logic, iOS reset behavior
+src/commands/version/update.ts      ← file write targets, backup triggers
+src/commands/project/generate.ts    ← module template content, class naming
+src/commands/project/devices.ts     ← device listing, run, run-select
+src/commands/project/open.ts        ← open commands, OS-specific logic
+src/commands/project/setup.ts       ← VSCode settings template
+src/commands/config/init.ts         ← init defaults, gitignore logic
+src/commands/config/rollback.ts     ← backup search, restore, grouping
+src/utils/helpers/version.ts        ← version parsing, iOS build read source
+src/utils/services/backup.ts        ← backup naming, retention, structure
+src/utils/services/config.ts        ← config lookup order
+src/utils/validators/validation.ts  ← what each validator checks
+```
+
+---
+
+## Step 2 — Check What Changed
+
+Compare what you read in Step 1 against each documentation file below. For each file, identify:
+- Commands that no longer exist → remove them
+- New commands → add them
+- Changed flags or behavior → update descriptions
+- Changed file paths or output paths → update references
+- Changed retry counts, timeouts, or defaults → update numbers
+
+---
+
+## Step 3 — Update Each Doc File
+
+Update all files that are out of sync. Do not touch files that are already accurate.
+
+### `CLAUDE.md` (root)
+Tracks the developer-facing architecture of the CLI itself. Update when:
+- Folder structure changes (new command files, new utilities)
+- New utility functions are added to helpers/services
+- Adding new commands section changes
+- FVM behavior, retry config, or version flow changes
+- Important notes change (ES module rules, path patterns, etc.)
+
+Key sections to check:
+- Folder Structure tree
+- Each utility module's function list
+- Version Management Flow steps
+- iOS Build Pattern retry numbers
+- Adding New Commands checklist
+
+### `docs/USAGE.md`
+End-user command reference. Update when any command is added, removed, or its flags change.
+
+Sections to check:
+- Configuration Commands
+- Version Management Commands
+- Device Management Commands
+- Build Commands
+- Clean Commands
+- Project Commands
+
+### `docs/VERSION_MANAGEMENT.md`
+Deep dive into version strategy. Update when:
+- bump command behavior changes (especially iOS reset logic)
+- New bump-* commands are added
+- Files modified by version commands change
+- Command reference table changes
+
+### `docs/SAFETY_FEATURES.md`
+Backup system and validation docs. Update when:
+- New files get backed up
+- Backup retention count changes
+- New validators are added
+- Error messages change
+
+### `docs/INSTALLATION.md`
+Update only if install method or prerequisites change.
+
+### `docs/TROUBLESHOOT.md`
+Update if new error messages are added or error handling changes.
+
+### `OPTIKIT_AGENT.md` (root)
+AI agent reference — the most important file to keep accurate. Update when ANYTHING changes:
+- Any command flag, behavior, or output
+- File paths modified by commands
+- Retry counts, timeouts, defaults
+- Class naming conventions in generate
+- Backup structure or naming
+
+### `.claude/commands/version.md`
+Update when: bump commands change, files modified change, manual version flags change.
+
+### `.claude/commands/build.md`
+Update when: build flags change, output paths change, new artifact types added.
+
+### `.claude/commands/clean.md`
+Update when: clean steps change, retry config changes, new clean flags added.
+
+### `.claude/commands/generate.md`
+Update when: generated file structure changes, class naming changes, template content changes.
+
+### `.claude/commands/run.md`
+Update when: run flags change, device listing format changes, new run options added.
+
+### `.claude/commands/rollback.md`
+Update when: backup structure changes, new files are backed up, retention count changes.
+
+### `.claude/commands/setup.md`
+Update when: init defaults change, VSCode settings template changes, new setup commands added.
+
+---
+
+## Step 4 — Cross-Check References
+
+After updating, verify:
+- All file path references in `CLAUDE.md` match actual files in `src/`
+- All `docs/` cross-links still point to files that exist in `docs/`
+- `README.md` links to `docs/` files all use the `docs/` prefix
+- `OPTIKIT_AGENT.md` command table has no missing or phantom commands vs `src/cli.ts`
+
+---
+
+## Step 5 — Report What Changed
+
+After finishing, summarize:
+1. Which docs were updated and why
+2. Which docs were already accurate (no changes needed)
+3. Any inconsistencies found that couldn't be auto-resolved

package/.claude/commands/version.md

@@ -0,0 +1,63 @@
+# OptiKit Version Management
+
+Show current version info and bump or set version/build numbers for this Flutter project using the OptiKit CLI.
+
+## Current Version
+
+Run this first to see what we're working with:
+
+```bash
+optikit version
+```
+
+## Bump Version (Semantic Versioning)
+
+Based on the nature of the change, choose the right bump:
+
+| Change Type | Command | Effect |
+|---|---|---|
+| Bug fix | `optikit bump patch` | `1.2.3+45` → `1.2.4+46` (iOS: 1) |
+| New feature | `optikit bump minor` | `1.2.3+45` → `1.3.0+46` (iOS: 1) |
+| Breaking change | `optikit bump major` | `1.2.3+45` → `2.0.0+46` (iOS: 1) |
+
+iOS build resets to 1 on any version bump (App Store Connect expects this).
+Android build always increments (Google Play requires strictly increasing numbers).
+
+## Bump Build Numbers Only (No Version Change)
+
+| Platform | Command | Use Case |
+|---|---|---|
+| iOS only | `optikit bump-ios` | Another TestFlight upload |
+| Android only | `optikit bump-android` | Another Google Play upload |
+| Both | `optikit bump-build` | Simultaneous upload to both stores |
+
+## Manual Version Override
+
+When you need to set exact numbers:
+
+```bash
+optikit flutter-update-version \
+  --app-version <X.Y.Z> \
+  --android-build <number> \
+  --ios-build <number>
+```
+
+All three flags are optional — omit any to skip updating that platform.
+
+## Files Modified
+
+Every version command backs up these files before writing:
+1. `pubspec.yaml` — `version: X.Y.Z+B`
+2. `ios/Runner.xcodeproj/project.pbxproj` — `MARKETING_VERSION`, `CURRENT_PROJECT_VERSION`
+3. `ios/Runner/Info.plist` — `CFBundleShortVersionString`, `CFBundleVersion`
+
+## Rollback If Something Went Wrong
+
+```bash
+optikit rollback              # list all backups with timestamps
+optikit rollback --restore 1  # restore the most recent backup
+```
+
+---
+
+Now look at the user's request and run the appropriate command(s) above.

package/.claude/settings.local.json

@@ -0,0 +1,28 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(grep -E \"\\\\.\\(ts|md|json\\)$\")",
+      "Bash(gh api:*)",
+      "Bash(find /Users/elshenawy/My-CLI/optikit/src -type f -name *.ts)",
+      "WebFetch(domain:pub.dev)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(npm run:*)",
+      "Bash(node:*)",
+      "Bash(file:*)",
+      "Bash(wc:*)",
+      "mcp__plugin_claude-mem_mcp-search__get_observations",
+      "Bash(npm link:*)",
+      "Bash(ok --version)",
+      "Bash(npm install:*)",
+      "Bash(python3 -c \"import sys,json; d=json.load\\(sys.stdin\\)[''''exports'''']; [print\\(k\\) for k in d.keys\\(\\)]\")",
+      "Bash(grep -E '^\\\\s+command:' /Users/elshenawy/My-CLI/optikit/src/commands/*/commands.ts)",
+      "Bash(printf '{\"\"\"\"jsonrpc\"\"\"\":\"\"\"\"2.0\"\"\"\",\"\"\"\"id\"\"\"\":1,\"\"\"\"method\"\"\"\":\"\"\"\"initialize\"\"\"\",\"\"\"\"params\"\"\"\":{\"\"\"\"protocolVersion\"\"\"\":\"\"\"\"2024-11-05\"\"\"\",\"\"\"\"capabilities\"\"\"\":{},\"\"\"\"clientInfo\"\"\"\":{\"\"\"\"name\"\"\"\":\"\"\"\"test\"\"\"\",\"\"\"\"version\"\"\"\":\"\"\"\"1.0\"\"\"\"}}}\\\\n')",
+      "Bash(gtimeout 5 node dist/cli.js mcp)",
+      "Bash(python3 -m json.tool)",
+      "Bash(python3:*)",
+      "WebSearch",
+      "Bash(git add:*)"
+    ]
+  }
+}

package/.claude-plugin/marketplace.json

@@ -0,0 +1,36 @@
+{
+  "name": "optikit-marketplace",
+  "owner": {
+    "name": "Mahmoud El Shenawy",
+    "email": "dev.m.elshenawy@icloud.com"
+  },
+  "plugins": [
+    {
+      "name": "optikit",
+      "source": {
+        "source": "github",
+        "repo": "dev-mahmoud-elshenawy/optikit"
+      },
+      "description": "Build, version, and deploy Flutter apps in one CLI. 28 MCP tools for builds, versioning, module scaffolding, and project maintenance.",
+      "version": "1.3.0",
+      "author": {
+        "name": "Mahmoud El Shenawy"
+      },
+      "homepage": "https://github.com/dev-mahmoud-elshenawy/optikit",
+      "repository": "https://github.com/dev-mahmoud-elshenawy/optikit",
+      "license": "MIT",
+      "keywords": [
+        "flutter",
+        "opticore",
+        "build",
+        "version-management",
+        "testflight",
+        "apk",
+        "ipa",
+        "bloc",
+        "fvm",
+        "cli"
+      ]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "optikit",
+  "version": "1.3.0",
+  "description": "Build, version, and deploy Flutter apps in one CLI. 28 MCP tools for builds, versioning, module scaffolding, and project maintenance.",
+  "author": {
+    "name": "Mahmoud El Shenawy",
+    "url": "https://github.com/dev-mahmoud-elshenawy"
+  },
+  "homepage": "https://github.com/dev-mahmoud-elshenawy/optikit",
+  "repository": "https://github.com/dev-mahmoud-elshenawy/optikit",
+  "license": "MIT",
+  "keywords": [
+    "flutter",
+    "opticore",
+    "build",
+    "version-management",
+    "testflight",
+    "apk",
+    "ipa",
+    "bloc",
+    "fvm",
+    "cli"
+  ],
+  "mcpServers": "./.mcp.json"
+}