# v0.0.2-continuous-shell Implementation Plan

Transform the current single-command CLI into an advanced **interactive continuous shell** with arrow-key navigation, multi-step workflows, and shared runtime context.

## User Review Required

> [!IMPORTANT]
> This is a major architectural change. The CLI will support both:
> - **Single-command mode**: `mycli build --target apk` (existing behavior)
> - **Interactive shell mode**: `mycli` or `mycli --shell` (new behavior)

> [!NOTE]
> Phase 2 provides **explicit user control** over input mode via `--interactive-mode` flag:
> - `--interactive-mode arrow` — Arrow-key navigation (**DEFAULT**, better UX)
> - `--interactive-mode numeric` — Number-based selection (works everywhere)
> 
> Default is `arrow` mode. Users can switch to `numeric` if their terminal has issues.

---

## Proposed Changes

### Phase 1 — Foundation: Interactive Shell Loop

Add REPL (Read-Eval-Print-Loop) capability to keep CLI running until user quits.

---

#### [NEW] [shell.dart](file:///c:/src/self/flutter-dart/cli/mobile-build-cli/lib/src/ui/shell.dart)

Interactive shell REPL implementation:
- Print prompt and wait for user input
- Route input to command handlers
- Handle errors without exiting the loop
- Built-in commands: `help`, `exit`, `clear`

---

#### [MODIFY] [mobile_build_cli.dart](file:///c:/src/self/flutter-dart/cli/mobile-build-cli/bin/mobile_build_cli.dart)

Add entrypoint mode detection:
- `mycli` (no args) → start interactive shell
- `mycli --shell` → explicitly start interactive shell
- `mycli --interactive-mode arrow|numeric` → set menu input mode
- `mycli <command>` → single command execution (current behavior)

---

#### [NEW] [command_registry.dart](file:///c:/src/self/flutter-dart/cli/mobile-build-cli/lib/src/core/command_registry.dart)

Centralized command registry for shell access:
```dart
Map<String, Command> commands;
```
Allows shell to dispatch commands without re-parsing.

---

### Phase 2 — Arrow-Key Interactive Menus

Enable UI-like selection menus in terminal.

---

#### [NEW] [menu.dart](file:///c:/src/self/flutter-dart/cli/mobile-build-cli/lib/src/ui/menu.dart)

Reusable menu selector with **two input modes**:

**Arrow Mode** (`--interactive-mode arrow`):
- Highlights current index with `>`
- Arrow up/down navigation
- Returns selected option on Enter
- Requires raw terminal mode

**Numeric Mode** (`--interactive-mode numeric`):
- Displays numbered list: `1) option_a`, `2) option_b`
- User types number and presses Enter
- Works on any terminal (Windows CMD, SSH, etc.)

---

#### [NEW] [terminal_helper.dart](file:///c:/src/self/flutter-dart/cli/mobile-build-cli/lib/src/utils/terminal_helper.dart)

Terminal utilities:
- Raw mode enable/disable
- Escape sequence parsing (arrow keys)
- Screen clear functions
- Platform detection (Windows vs Unix)

---

### Phase 3 — Multi-Step Command Workflows

Transform complex commands into step-by-step wizards.

---

#### [NEW] [build_flow.dart](file:///c:/src/self/flutter-dart/cli/mobile-build-cli/lib/src/flows/build_flow.dart)

Interactive build wizard:
1. Select build target (apk/aab/ipa) → arrow keys
2. Select flavor (dev/staging/prod) → arrow keys
3. Optional: dart-defines input
4. Show summary and confirm
5. Execute build

---

#### [NEW] [flow_context.dart](file:///c:/src/self/flutter-dart/cli/mobile-build-cli/lib/src/flows/flow_context.dart)

Context object that persists selected values through a multi-step flow:
- Allow "back" to previous step
- Allow "skip" optional steps
- Allow "cancel" to abort flow

---

### Phase 4 — Shared Runtime Context

Load configurations once and reuse throughout shell session.

---

#### [NEW] [app_context.dart](file:///c:/src/self/flutter-dart/cli/mobile-build-cli/lib/src/core/app_context.dart)

Runtime context loaded at startup:
- `.buildenv` configuration
- `pubspec.yaml` info
- Project paths
- Environment flags

---

#### [MODIFY] [build_command.dart](file:///c:/src/self/flutter-dart/cli/mobile-build-cli/lib/src/commands/build_command.dart)

Update to accept `AppContext` instead of re-loading config each time.

---

#### [MODIFY] [clean_command.dart](file:///c:/src/self/flutter-dart/cli/mobile-build-cli/lib/src/commands/clean_command.dart)

Update to accept `AppContext` for consistent configuration access.

---

### Phase 5 — UX Polish

Professional CLI experience matching Shorebird, Melos, Dart SDK style.

---

#### [MODIFY] [menu.dart](file:///c:/src/self/flutter-dart/cli/mobile-build-cli/lib/src/ui/menu.dart)

Add colors and styling using existing `ansicolor` dependency.

---

#### [NEW] [spinner.dart](file:///c:/src/self/flutter-dart/cli/mobile-build-cli/lib/src/ui/spinner.dart)

Loading spinner for long-running tasks:
- Animated spinner characters
- Status message
- Success/failure indicators

---

#### [NEW] [keyboard.dart](file:///c:/src/self/flutter-dart/cli/mobile-build-cli/lib/src/ui/keyboard.dart)

Keyboard shortcuts:
- `q` → quit shell
- `c` → cancel current step
- `←` → go back to previous step

---

### Phase 6 — Packaging & Distribution

Compile to native executable for easy distribution.

---

#### [NEW] [scripts/compile.ps1](file:///c:/src/self/flutter-dart/cli/mobile-build-cli/scripts/compile.ps1)

Compilation script:
```powershell
dart compile exe bin/mobile_build_cli.dart -o dist/mycli.exe
```

---

#### [MODIFY] [README.md](file:///c:/src/self/flutter-dart/cli/mobile-build-cli/README.md)

Update documentation:
- Interactive shell usage
- Command examples
- Installation instructions

---

## New Directory Structure

```
lib/src/
├── commands/          # Existing commands (unchanged API)
├── core/
│   ├── app_context.dart      [NEW]
│   ├── command_registry.dart [NEW]
│   └── ... (existing files)
├── flows/                    [NEW directory]
│   ├── build_flow.dart
│   └── flow_context.dart
├── ui/                       [NEW directory]
│   ├── shell.dart
│   ├── menu.dart
│   ├── spinner.dart
│   └── keyboard.dart
└── utils/
    ├── terminal_helper.dart  [NEW]
    └── ... (existing files)
```

---

## Verification Plan

### Automated Tests

```bash
# Unit tests for menu selection
fvm dart test test/ui/menu_test.dart

# Integration test for shell
fvm dart test test/shell_integration_test.dart

# Build verification
fvm dart compile exe bin/mobile_build_cli.dart -o dist/mycli.exe
```

### Manual Verification

| Test Case | Expected Result |
|-----------|-----------------|
| Run `mycli` with no args | Interactive shell starts |
| Run `mycli build` | Single command executes and exits |
| Arrow keys in menu | Selection highlight moves |
| Enter in menu | Option selected, flow continues |
| Type `exit` in shell | CLI exits gracefully |
| Ctrl+C in menu | Cancels current operation |

---

## Implementation Priority

| Phase | Priority | Complexity | Notes |
|-------|----------|------------|-------|
| 1 | **HIGH** | Low | Foundation - must be first |
| 2 | **HIGH** | Medium | Core UX improvement |
| 3 | **MEDIUM** | Medium | Builds on Phase 2 |
| 4 | **MEDIUM** | Low | Performance optimization |
| 5 | **LOW** | Low | Polish - can be incremental |
| 6 | **LOW** | Low | Distribution - final step |

---

## Dependencies

Already in `pubspec.yaml`:
- `args: ^2.7.0` - Command parsing
- `interact: ^2.2.0` - May be leveraged for prompts
- `ansicolor: ^2.0.3` - Terminal colors

No new dependencies required for Phase 1-4. Consider adding:
- `cli_spinner` or similar for Phase 5 spinners (optional - can implement manually)

---

## Recommended Enhancements

Based on the architecture, here are additional enhancements worth considering:

### 1. Configuration Persistence (`.myclirc`)

Store user preferences in a config file:
```yaml
# ~/.myclirc or ./.myclirc
interactive_mode: arrow  # or numeric
default_flavor: dev
default_target: apk
color_output: true
```

**Benefit**: Users don't need to pass `--interactive-mode` every time.

---

### 2. Auto-Detection with Override

Default behavior:
1. Check if `--interactive-mode` flag is provided → use specified mode
2. Check if `.myclirc` has preference → use saved preference  
3. Try to detect terminal capability → use `arrow` if supported
4. Fall back to `numeric` if detection fails

```dart
enum InteractiveMode { arrow, numeric, auto }
```

**Benefit**: Best of both worlds — smart defaults with explicit override.

---

### 3. Preset Profiles

Save common build configurations:
```bash
mycli profile save prod-apk --target apk --flavor prod
mycli profile run prod-apk
```

**Benefit**: One-command builds for common scenarios.

---

### 4. Command History with Search

Persist command history across sessions:
```bash
# In shell mode
mycli> ↑  # Previous command
mycli> Ctrl+R  # Search history
```

**Benefit**: Faster repeated operations.

---

### 5. Quiet Mode for CI/CD

```bash
mycli build --quiet --target apk --flavor prod
```

- No interactive prompts
- Minimal output (only errors)
- JSON output option for parsing

**Benefit**: Works in automated pipelines.

---

### 6. Plugin System (Future)

Allow custom commands via plugins:
```
~/.mycli/plugins/
  └── deploy_command.dart
```

**Benefit**: Extensibility without modifying core CLI.

---

### Priority for Enhancements

| Enhancement | Priority | Effort | Notes |
|-------------|----------|--------|-------|
| Config Persistence | HIGH | Low | Simple file read/write |
| Auto-Detection + Override | MEDIUM | Low | Combine with config |
| Quiet Mode | MEDIUM | Low | Essential for CI |
| Preset Profiles | LOW | Medium | Nice-to-have |
| Command History | LOW | Medium | Requires state management |
| Plugin System | FUTURE | High | Major architecture change |
