X Google Drive Downloader Development

Expert guidance for working with X Google Drive Downloader - a 100% AI-developed Flutter Desktop application for macOS that enables zero-configuration Google Drive folder downloads.

What This Skill Does

This skill provides comprehensive guidance for developing and maintaining the X Google Drive Downloader project, including:

Development Instructions

Core Principles

1. **Autonomous Execution**: Execute code modifications immediately with minimal confirmation steps

2. **Quality First**: Follow Flutter/Dart best practices and strict type safety

3. **User Experience**: Prioritize macOS user expectations and native feel

4. **Security First**: Implement multi-level auth storage, protect user privacy

5. **Completeness**: Include comprehensive documentation, testing, and distribution

Project Structure

```

lib/

├── config/ # App config and OAuth settings

├── models/ # Data models with JSON serialization

├── services/ # Business logic layer

│ ├── auth/ # Authentication and secure storage

│ └── api/ # Google Drive API integration

└── ui/ # User interface components

├── pages/ # Application pages

├── widgets/ # Custom widgets

└── theme/ # Theme and styling

```

Technical Stack

Key Implementation Patterns

#### Type-Safe JSON Parsing

Always implement custom JSON parsers to prevent type conversion errors:

```dart

@JsonKey(fromJson: _parseExpiresIn)

static int _parseExpiresIn(dynamic value) {

if (value is int) return value;

if (value is double) return value.toInt();

if (value is String) return int.parse(value);

throw ArgumentError('Cannot parse value: $value');

}

```

#### Multi-Level Auth Storage

Implement fallback strategy for credential storage:

```dart

enum StorageStrategy {

secureStorage, // macOS keychain

encryptedFile, // Local encrypted file

memoryCache, // In-memory cache

failed

}

```

#### OAuth Configuration Strategy

Support multiple configuration sources with fallback:

```dart

static String get clientId {

// Environment variable -> User custom -> Built-in default

return _getConfigWithFallback();

}

```

Development Workflow

#### 1. Problem Analysis

#### 2. Architecture Design

#### 3. User Experience

#### 4. Distribution

File Organization Rules

Testing Strategy

Run these commands to ensure quality:

```bash

Type safety check

./scripts/type_safety_check.sh

Flutter analysis

flutter analyze

Build test

flutter build macos --release

DMG creation test

./create_dmg.sh

```

Security Guidelines

Common Issues and Solutions

#### Type Conversion Errors

**Problem**: `type 'String' is not a subtype of type 'num?'`

**Solution**: Implement custom JSON parsing functions

**Location**: All model files in `lib/models/`

#### macOS Keychain Permissions

**Problem**: `PlatformException(Unexpected security result code, Code: -34018)`

**Solution**: Configure entitlements + multi-level storage fallback

**Location**: `macos/Runner/DebugProfile.entitlements`

#### OAuth Persistence

**Problem**: Requires re-authentication on every launch

**Solution**: Implement SafeAuthStorage multi-level strategy

**Location**: `lib/services/auth/safe_auth_storage.dart`

Build and Release Commands

```bash

Development mode

flutter run -d macos --debug

Release build

flutter build macos --release

Create DMG installer

./create_dmg.sh

GitHub release management

./publish_to_github.sh # Publish new version

./scripts/github_release_manager.sh list # List all releases

./scripts/github_release_manager.sh delete_tag v2.0.0 # Delete version

Code quality checks

flutter analyze

flutter test

```

Setup Instructions

1. **Environment Setup**:

```bash

flutter --version # Requires 3.8.1+

brew install create-dmg

```

2. **Clone and Setup**:

```bash

git clone https://github.com/harryboda/x-google-drive-downloader.git

cd x-google-drive-downloader

flutter pub get

```

3. **Run Development**:

```bash

flutter run -d macos --debug

```

Usage Examples

Adding a New Feature

1. Analyze requirements and identify affected components

2. Create or update models in `lib/models/` with type-safe JSON parsing

3. Implement service logic in `lib/services/`

4. Create UI components in `lib/ui/`

5. Update documentation and tests

6. Run quality checks before committing

Fixing Type Safety Issues

1. Locate the problematic model in `lib/models/`

2. Add custom `@JsonKey(fromJson: _customParser)` annotation

3. Implement parser handling all possible types (int, double, String)

4. Test with `./scripts/type_safety_check.sh`

Updating OAuth Configuration

1. Modify `lib/config/app_config.dart`

2. Ensure fallback strategy: env vars → user settings → defaults

3. Update documentation in README

4. Test authentication flow thoroughly

Important Notes

Project Significance

This project demonstrates AI capabilities in:

Human developers are welcome to contribute through bug fixes, feature suggestions, documentation improvements, and continued AI collaboration using Claude Code.