optikit 1.2.4 → 1.3.0

package/CLAUDE.md

@@ -2,238 +2,89 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Project Overview
+## Related Documentation
 
-OptiKit is a TypeScript-based CLI tool for Flutter developers, especially those using the Opticore micro framework. It automates module scaffolding, build processes, and project maintenance tasks.
+| File | Purpose |
+|---|---|
+| [OPTIKIT_AGENT.md](OPTIKIT_AGENT.md) | Full AI agent reference — deep command details, behaviors, constraints |
+| [docs/USAGE.md](docs/USAGE.md) | End-user command reference |
+| [docs/VERSION_MANAGEMENT.md](docs/VERSION_MANAGEMENT.md) | Version bump strategy and dual build number system |
+| [docs/INSTALLATION.md](docs/INSTALLATION.md) | Installation methods (NPM, Homebrew, source) |
 
-## Essential Commands
+## Claude Slash Commands (`.claude/commands/`)
 
-### Development
-```bash
-npm install              # Install dependencies
-npm run build           # Compile TypeScript to dist/
-npm start               # Run the CLI (after build)
-node dist/cli.js        # Direct execution
-```
+These commands can be copied into any Flutter project that uses OptiKit:
 
-### Testing the CLI Locally
-```bash
-npm link                # Create global symlink for testing
-optikit <command>       # Test commands globally
-npm unlink              # Remove symlink when done
-```
-
-### Build Configuration
-- TypeScript compiles from `src/` to `dist/`
-- Target: ESNext, Module: NodeNext
-- Entry point: `src/cli.ts` (shebang for CLI execution)
-- Binary: `dist/cli.js` (executable as `optikit` command)
+| Command | Triggers |
+|---|---|
+| `/version` | Show, bump, or manually set version/build numbers |
+| `/build` | Build APK, AAB, iOS, or IPA |
+| `/clean` | Clean Flutter project or iOS CocoaPods |
+| `/generate` | Scaffold a BLoC module for Opticore |
+| `/run` | List devices and run the app |
+| `/rollback` | Inspect and restore backups |
+| `/setup` | Init config and VSCode settings |
+| `/sync-docs` | Keep all docs in sync after any source change |
 
-## Architecture
+> After any change to `src/`, run `/sync-docs` to update all documentation automatically.
 
-### Folder Structure (Domain-Based Organization)
-
-```
-src/
-├── cli.ts                          # Main CLI entry point (yargs configuration)
-├── constants.ts                    # Centralized constants and configurations
-├── styles.ts                       # CLI styling (boxen, chalk)
-│
-├── commands/                       # Domain-organized command modules
-│   ├── build/                      # Build-related commands
-│   │   └── releases.ts             # APK, Bundle, IPA, iOS builds
-│   ├── clean/                      # Clean-related commands
-│   │   ├── flutter.ts              # Flutter project cleaning
-│   │   └── ios.ts                  # iOS-specific cleaning
-│   ├── version/                    # Version management commands
-│   │   ├── bump.ts                 # Smart version bumping (major/minor/patch, iOS/Android)
-│   │   └── update.ts               # Manual version updates
-│   ├── project/                    # Project-related commands
-│   │   ├── generate.ts             # Module generation (BLoC pattern)
-│   │   ├── open.ts                 # Open in Xcode/Android Studio
-│   │   └── setup.ts                # VSCode settings setup
-│   └── config/                     # Configuration commands
-│       ├── init.ts                 # Initialize OptiKit config
-│       └── rollback.ts             # Backup management
-│
-└── utils/                          # Categorized utility modules
-    ├── validators/                 # Validation utilities
-    │   └── validation.ts           # Flutter project, SDK, iOS/Android validation
-    ├── helpers/                    # Helper functions
-    │   ├── build.ts                # Build execution helpers
-    │   ├── dryRun.ts               # Dry-run mode utilities
-    │   ├── file.ts                 # File operations (create, write, getClassName)
-    │   ├── string.ts               # String manipulation (capitalize, etc.)
-    │   └── version.ts              # Version parsing and manipulation
-    └── services/                   # Service modules
-        ├── backup.ts               # Automatic backup/restore system
-        ├── command.ts              # Command validation helpers
-        ├── config.ts               # .optikitrc configuration management
-        ├── exec.ts                 # Process execution (execCommand, execInIos)
-        └── logger.ts               # Colored console output (chalk)
-```
-
-### Command Structure
-All commands are defined in [src/cli.ts](src/cli.ts) using yargs and implemented in domain-specific modules under `src/commands/`:
-
-**Command Registry Pattern:**
-```
-cli.ts (yargs configuration)
-  ├── Import command modules from domain folders
-  └── Define command specs with:
-      ├── Command name and arguments
-      ├── Options (flags like --disable-fvm)
-      └── Handler function (calls command module)
-```
-
-### Module Generation System
-The `generate module` command creates a complete BLoC pattern structure for Opticore framework:
+## Essential Commands
 
-**Generated Structure:**
-```
-lib/module/<moduleName>/
-  ├── bloc/        # BLoC implementation
-  ├── event/       # Event definitions
-  ├── state/       # State definitions
-  ├── screen/      # UI screen widgets
-  ├── factory/     # State factory
-  └── import/      # Centralized imports file
+```bash
+npm install              # Install dependencies
+npm run build            # Compile TypeScript (src/ -> dist/)
+npm start                # Run CLI (equivalent to node dist/cli.js)
+npm link                 # Create global symlink for local testing
+optikit <command>        # Test commands after npm link
 ```
 
-**Template System:**
+**No test suite exists** — `npm test` is a stub. There is no linter configured.
 
-- Each component type has a template in [src/commands/project/generate.ts](src/commands/project/generate.ts)
-- Uses `part of` syntax linking to central import file
-- Class names auto-generated via `getClassName()` utility
-- All files use `.dart` extension and follow Opticore patterns
-
-### Utility Modules
-
-#### Validators (src/utils/validators/)
-
-**validation.ts** - Pre-flight validation system:
-
-- `validateFlutterProject()` - Checks for pubspec.yaml
-- `validateFlutterSdk(useFvm)` - Validates Flutter/FVM installation
-- `validateIosProject()` - Checks iOS project structure
-- `validateAndroidProject()` - Checks Android project structure
-
-#### Helpers (src/utils/helpers/)
-
-**exec.ts** (in services/) - Process execution with three patterns:
-
-1. `execCommand(command)` - Spawns shell command with streaming output
-2. `execInIos(command)` - Runs command in `ios/` directory with 10min timeout
-3. `execInIosWithRetry(command, retries, delay)` - Retry wrapper for flaky network operations
-
-**file.ts** - File operations:
-
-- `createDirectories(basePath, dirs)` - Recursive directory creation
-- `writeFile(path, content)` - Write with error handling
-- `getClassName(moduleName, suffix)` - Converts snake_case to PascalCase (e.g., "user_profile" → "UserProfileBloc")
-
-**version.ts** - Version management:
-
-- `parseVersion(versionString)` - Parses version in X.Y.Z+B format
-- `incrementVersion(current, type)` - Handles major/minor/patch increments
-- `getCurrentVersion()` - Reads version from pubspec.yaml
-- `formatVersion(version)` - Formats version to string
-
-**build.ts** - Build execution:
-
-- `executeBuild(config, noFvm)` - Unified build execution with validation
-
-**string.ts** - String utilities (capitalize, etc.)
-
-#### Services (src/utils/services/)
-
-**logger.ts** - Colored console output using chalk:
-
-- `.success()` - Green
-- `.error()` - Red
-- `.warning()` - Yellow
-- `.info()` - Light blue
+## Project Overview
 
-**backup.ts** - Automatic backup system:
+OptiKit is a TypeScript CLI for Flutter/Opticore developers. It automates module scaffolding, builds, version management, and project maintenance. Built with yargs, chalk, and boxen.
 
-- `createBackup(filePath)` - Creates timestamped backups in .optikit-backup/
-- `restoreBackup(originalPath, backupPath)` - Restores from backup
-- `cleanupBackups(directory, retentionCount)` - Maintains backup retention limit
+## Architecture
 
-**config.ts** - Configuration management:
+### How Commands Work
 
-- `loadConfig()` - Loads .optikitrc.json from project or home directory
-- `saveConfig(config)` - Saves configuration to file
-- Priority: project .optikitrc → project .optikitrc.json → home directory versions
+All commands are registered in `src/cli.ts` using yargs `.command()` blocks. Each block imports a handler from a domain module under `src/commands/`. The pattern:
 
-**command.ts** - Command utilities:
+1. `cli.ts` defines the command name, positional args, options (flags), and description
+2. The handler function delegates to the imported command module
+3. Command modules use utilities from `src/utils/` (validators, helpers, services)
 
-- Validation and command helpers
+### Domain Organization
 
-### FVM Support Pattern
-Most Flutter commands support `--disable-fvm` flag:
-- Default: Prepends `fvm` to Flutter/Dart commands
-- With flag: Uses global Flutter SDK
-- Used in: build commands, clean commands
+Commands are grouped by domain: `build/`, `clean/`, `version/`, `project/`, `config/`. Utilities are grouped by role: `validators/`, `helpers/`, `services/`.
 
-### Version Management Flow
-The `flutter-update-version` command handles cross-platform versioning:
-1. Updates `pubspec.yaml` (version + build number)
-2. Updates `ios/Runner.xcodeproj/project.pbxproj` (MARKETING_VERSION, CURRENT_PROJECT_VERSION)
-3. Updates `ios/Runner/Info.plist` (CFBundleShortVersionString, CFBundleVersion)
-4. Runs `agvtool` commands in iOS directory for Xcode build settings
+### Key Architectural Patterns
 
-### iOS Build Pattern
-iOS commands use retry logic due to CocoaPods network instability:
-- Default: 3 retries with 5s delay
-- All iOS operations run in `ios/` directory via `execInIos()`
-- 10-minute timeout for pod operations
+**FVM Support** — Most Flutter commands support a `--disable-fvm` flag. By default, commands prepend `fvm` to Flutter/Dart commands. The flag switches to the global Flutter SDK. Constants for both variants live in `src/constants.ts` (`FLUTTER_COMMANDS` vs `FVM_COMMANDS`).
 
-## File Naming Conventions
+**Version Management (Dual Build Numbers)** — Android and iOS have independent build numbers. `bump <type>` increments the semver and resets both. `bump-ios` / `bump-android` / `bump-build` increment build numbers independently. Version updates touch three files simultaneously: `pubspec.yaml`, `ios/Runner.xcodeproj/project.pbxproj`, and `ios/Runner/Info.plist`.
 
-### TypeScript Files (Domain-Based)
+**Backup System** — Before modifying version files, OptiKit creates timestamped backups in `.optikit-backup/`. Retention is capped at 5 backups (configurable in `constants.ts` `BACKUP_CONFIG`). The `rollback` command lists and restores these.
 
-**Commands** - Organized by domain in `src/commands/`:
+**Process Execution** — Three execution patterns in `src/utils/services/exec.ts`: `execCommand()` for general shell commands with streaming output, `execInIos()` for commands in `ios/` with 10-min timeout, and `execInIosWithRetry()` for flaky CocoaPods operations (3 retries, 10s delay).
 
-- `build/releases.ts` - Build commands
-- `clean/flutter.ts`, `clean/ios.ts` - Clean commands
-- `version/bump.ts`, `version/update.ts` - Version commands
-- `project/generate.ts`, `project/open.ts`, `project/setup.ts` - Project commands
-- `config/init.ts`, `config/rollback.ts` - Configuration commands
+**Module Generation** — The `generate module` command scaffolds a complete BLoC pattern: bloc, event, state, screen, factory, and import file. Templates are inline in `src/commands/project/generate.ts`. Class names are derived from snake_case module names via `getClassName()` (e.g., `user_profile` -> `UserProfileBloc`).
 
-**Utilities** - Categorized in `src/utils/`:
+**Configuration** — `.optikitrc.json` loaded with priority: project root > home directory. Managed by `src/utils/services/config.ts`.
 
-- `validators/validation.ts` - Validation utilities
-- `helpers/*.ts` - Helper functions (build, file, string, version, dryRun)
-- `services/*.ts` - Service modules (backup, command, config, exec, logger)
-- All modules use ES6 imports with `.js` extension (TypeScript quirk for NodeNext)
+**Constants** — All magic strings, paths, commands, error messages, and build configs are centralized in `src/constants.ts`. Always use these rather than inline strings.
 
-### Generated Dart Files
+## Adding New Commands
 
-- Pattern: `<moduleName>_<type>.dart`
-- Types: `bloc`, `event`, `state`, `screen`, `factory`, `import`
-- Example: For module "user_profile" → `user_profile_bloc.dart`
+1. Create a command module in the appropriate domain folder under `src/commands/`
+2. Import it in `src/cli.ts` (use `.js` extension in imports — ES modules requirement)
+3. Add a `.command()` block following the existing pattern in cli.ts
+4. Use `LoggerHelpers` for output, `execCommand()` for shell ops, validators for pre-flight checks
 
-## Adding New Commands
+## Important Conventions
 
-1. **Choose the appropriate domain folder** in `src/commands/` (build, clean, version, project, config)
-2. **Create command module** in that folder (e.g., `src/commands/build/newBuild.ts`)
-3. **Import in [src/cli.ts](src/cli.ts)** using the new path (e.g., `./commands/build/newBuild.js`)
-4. **Add `.command()` block** with:
-   - Command signature
-   - Description
-   - Options configuration
-   - Handler calling your module function
-5. **Use categorized utilities**:
-   - `LoggerHelpers` from `../utils/services/logger.js` for console output
-   - `execCommand()` from `../utils/services/exec.js` for shell operations
-   - `validateFlutterProject()` from `../utils/validators/validation.js` for validation
-   - `createBackup()` from `../utils/services/backup.js` for backups
-
-## Important Notes
-
-- **ES Modules**: Project uses `"type": "module"` - all imports need `.js` extension
-- **Path Construction**: Use `path.join()` for cross-platform compatibility
-- **Error Handling**: Wrap async operations in try-catch, log with `LoggerHelpers.error()`
-- **Process Execution**: Never use `exec()` directly - use helper functions for consistent output streaming
-- **Opticore Framework**: Generated modules assume Opticore package is installed in target Flutter project
+- **ES Modules**: `"type": "module"` — all imports must use `.js` extension even for `.ts` files
+- **Strict TypeScript**: `strict: true` in tsconfig, target ESNext with NodeNext module resolution
+- **Path construction**: Always use `path.join()` for cross-platform paths
+- **Process execution**: Never use `child_process` directly — use `execCommand()` / `execInIos()` wrappers
+- **Constants over strings**: Use `src/constants.ts` for paths, commands, error messages, and config values