# v0.0.3 Implementation Plan

Migrate BuildCraft CLI to use **`buildcraft.yaml`** as the single config source and implement **JSONL structured build logging**.

## User Review Required

> [!IMPORTANT]
> This is a **breaking change** release. The old `.buildenv` KEY=VALUE config format will be completely replaced.

> [!WARNING]
> The `gen-env` command will be removed. Users must manually create `buildcraft.yaml`.

---

## Proposed Changes

### Phase 1 — YAML Configuration System

Replace `.buildenv` KEY=VALUE format with structured YAML configuration.

---

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

New config model with YAML loading:

```dart
class BuildConfig {
  final String appName;
  final String version;      // "1.2.3+45" full version
  final String buildType;    // apk, aab, ipa
  final String? flavor;
  final String outputPath;
  final FvmConfig? fvm;
  final ShorebirdConfig? shorebird;
  final List<DartDefine> dartDefines;
  
  static Future<BuildConfig> load(String path) async { ... }
}
```

---

#### Proposed `buildcraft.yaml` Schema

Based on existing `buildenv.base` keys:

```yaml
# buildcraft.yaml - Build Configuration
# Location: project root (same directory as pubspec.yaml)

# ──────────────────────────────────────────────
# App info (from pubspec or override here)
# ──────────────────────────────────────────────
app:
  name: app                  # APPNAME - app identifier

# ──────────────────────────────────────────────
# Core build settings
# ──────────────────────────────────────────────
build:
  name: 1.0.0                # BUILD_NAME - semantic version
  number: 1                  # BUILD_NUMBER - build number
  type: aab                  # BUILD_TYPE - aab | apk | ipa | app
  flavor: null               # FLAVOR - dev | staging | prod | null
  target: lib/main.dart      # TARGET_DART - main entry point

# ──────────────────────────────────────────────
# Output & Input paths
# ──────────────────────────────────────────────
paths:
  output: dist               # OUTPUT_PATH - output directory
  env: ./.env                # ENV_PATH - env file path

# ──────────────────────────────────────────────
# Build flags
# ──────────────────────────────────────────────
flags:
  use_dart_define: false     # USE_DART_DEFINE
  need_clean: false          # NEED_CLEAN
  need_build_runner: false   # NEED_BUILD_RUNNER

# ──────────────────────────────────────────────
# FVM integration
# ──────────────────────────────────────────────
fvm:
  enabled: false             # USE_FVM
  version: null              # FLUTTER_VERSION - pinned version

# ──────────────────────────────────────────────
# Shorebird integration
# ──────────────────────────────────────────────
shorebird:
  enabled: false             # USE_SHOREBIRD
  artifact: null             # SHOREBIRD_ARTIFACT - apk | aab
  auto_confirm: true         # SHOREBIRD_AUTO_CONFIRM --no-confirm

# ──────────────────────────────────────────────
# Bundletool (AAB → APK conversion)
# ──────────────────────────────────────────────
bundletool:
  path: null                 # BUNDLETOOL_PATH
  keystore: android/key.properties  # KEY_PROPERTIES_PATH
```

---

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

Remove legacy `.buildenv` parser. All references will migrate to `BuildConfig`.

---

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

Update to load `BuildConfig` instead of `BuildEnv`:

```diff
- final BuildEnv buildEnv;
+ final BuildConfig config;

- buildEnv = BuildEnv(projectRoot: projectRoot);
- await buildEnv.load();
+ config = await BuildConfig.load('buildcraft.yaml');
```

---

### Phase 2 — JSONL Build Record System

Implement structured logging with JSONL history and per-build logs.

---

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

JSONL record model:

```dart
class BuildRecord {
  final String id;           // UUID
  final String status;       // "success" | "failed"
  final String cmd;          // Full build command
  final double duration;     // Seconds
  final DateTime timestamp;  // UTC
  
  String toJsonLine() => jsonEncode(toMap());
}
```

---

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

JSONL history manager:

```dart
class BuildHistory {
  static const historyFile = '.buildcraft/build_history.jsonl';
  
  Future<void> append(BuildRecord record) async { ... }
  Future<List<BuildRecord>> readAll() async { ... }
  Future<BuildRecord?> lastBuild() async { ... }
}
```

---

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

Update log structure:

```diff
- logDirectory: 'dist/logs'
+ latestLog: '.buildcraft/build_latest.log'
+ perBuildLogs: '.buildcraft/logs/<uuid>.log'
```

New file locations:
```
.buildcraft/
├── build_history.jsonl     ← Append all builds (JSONL)
├── build_latest.log        ← Overwritten each run
└── logs/
    └── <uuid>.log          ← Per-build log file
```

---

### Phase 3 — Command Updates

Update all commands to use new config and logging.

---

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

- Replace `BuildEnv` with `BuildConfig`
- Integrate `BuildRecord` creation after build
- Stream logs to both `build_latest.log` and `logs/<uuid>.log`
- Append record to `build_history.jsonl` after completion

---

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

Remove command. YAML config is user-managed only.

---

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

Remove `gen-env` command registration.

---

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

Update to use `BuildConfig` for output path.

---

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

Update to use `BuildConfig` for bundletool settings.

---

### Phase 4 — Documentation & Version Bump

---

#### [NEW] [buildcraft.yaml.example](file:///c:/src/self/flutter-dart/cli/mobile-build-cli/buildcraft.yaml.example)

Example config template for users to copy.

---

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

- Update config documentation
- Remove `.buildenv` references
- Add `buildcraft.yaml` examples
- Document log file locations

---

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

```diff
- version: 0.0.2
+ version: 0.0.3
```

Add `uuid` dependency for build IDs.

---

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

Update version string and remove `gen-env` from known commands.

---

## New Directory Structure

```
.buildcraft/                          [NEW - log output directory]
├── build_history.jsonl
├── build_latest.log
└── logs/
    └── <uuid>.log

lib/src/core/
├── build_config.dart                 [NEW - replaces build_env.dart]
├── build_record.dart                 [NEW - JSONL record model]
├── build_history.dart                [NEW - JSONL history manager]
├── app_context.dart                  [MODIFY]
├── command_registry.dart             [MODIFY]
└── (build_env.dart)                  [DELETE]

lib/src/commands/
├── build_command.dart                [MODIFY]
├── clean_command.dart                [MODIFY]
├── convert_command.dart              [MODIFY]
└── (gen_env_command.dart)            [DELETE]
```

---

## Verification Plan

### Automated Tests

No existing automated tests to extend. The project uses manual testing.

```powershell
# 1. Static analysis
fvm dart analyze

# 2. Compile verification
fvm dart compile exe bin/buildcraft.dart -o dist/buildcraft-v0.0.3.exe
```

---

### Manual Verification

#### Test 1: Config Loading
1. Create `buildcraft.yaml` in a Flutter project root:
   ```yaml
   app:
     name: testapp
   build:
     type: apk
     output: dist
   ```
2. Run: `buildcraft --version`
3. **Expected**: Shows `buildcraft v0.0.3`

---

#### Test 2: Build with New Config
1. Run: `buildcraft` (start shell)
2. Type: `context`
3. **Expected**: Shows config loaded from `buildcraft.yaml`

---

#### Test 3: JSONL Logging
1. Run a build (or use `--dry-run` if available)
2. Check `.buildcraft/build_history.jsonl`
3. **Expected**: Contains one JSON line with `id`, `status`, `cmd`, `duration`, `timestamp`
4. Check `.buildcraft/build_latest.log`
5. **Expected**: Contains full build output

---

## Dependencies to Add

```yaml
dependencies:
  uuid: ^4.4.2  # For build record IDs
```

---

## Breaking Changes Summary

| Before (v0.0.2) | After (v0.0.3) |
|-----------------|----------------|
| `.buildenv` KEY=VALUE | `buildcraft.yaml` YAML |
| `buildenv.base` defaults | Removed (use YAML defaults) |
| `gen-env` command | Removed |
| Logs in `dist/logs/` | Logs in `.buildcraft/logs/` |
| Plain text history | JSONL history |
