@el-j/magic-helix-plugins 4.0.0-beta.6 → 4.0.0-beta.7

package/dist/dart/templates/flutter.md

@@ -0,0 +1,340 @@
+# Flutter Development Guidelines
+
+## Architecture & Structure
+
+### Project Organization
+```
+lib/
+├── main.dart
+├── app.dart
+├── core/
+│   ├── constants/
+│   ├── theme/
+│   └── utils/
+├── features/
+│   ├── auth/
+│   │   ├── data/
+│   │   ├── domain/
+│   │   └── presentation/
+│   └── home/
+└── shared/
+    ├── widgets/
+    └── models/
+```
+
+## Widget Best Practices
+
+### StatelessWidget
+```dart
+class UserCard extends StatelessWidget {
+  const UserCard({
+    super.key,
+    required this.user,
+    this.onTap,
+  });
+
+  final User user;
+  final VoidCallback? onTap;
+
+  @override
+  Widget build(BuildContext context) {
+    return Card(
+      child: ListTile(
+        title: Text(user.name),
+        subtitle: Text(user.email),
+        onTap: onTap,
+      ),
+    );
+  }
+}
+```
+
+### StatefulWidget
+```dart
+class Counter extends StatefulWidget {
+  const Counter({super.key});
+
+  @override
+  State<Counter> createState() => _CounterState();
+}
+
+class _CounterState extends State<Counter> {
+  int _count = 0;
+
+  @override
+  void dispose() {
+    // Clean up resources
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Column(
+      children: [
+        Text('Count: $_count'),
+        ElevatedButton(
+          onPressed: () => setState(() => _count++),
+          child: const Text('Increment'),
+        ),
+      ],
+    );
+  }
+}
+```
+
+## State Management
+
+### Riverpod (Recommended)
+```dart
+final userProvider = StateNotifierProvider<UserNotifier, AsyncValue<User>>((ref) {
+  return UserNotifier();
+});
+
+class UserNotifier extends StateNotifier<AsyncValue<User>> {
+  UserNotifier() : super(const AsyncValue.loading());
+
+  Future<void> fetchUser(String id) async {
+    state = const AsyncValue.loading();
+    state = await AsyncValue.guard(() => api.getUser(id));
+  }
+}
+
+// Usage in widget
+class UserProfile extends ConsumerWidget {
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final userState = ref.watch(userProvider);
+    
+    return userState.when(
+      data: (user) => Text(user.name),
+      loading: () => CircularProgressIndicator(),
+      error: (err, stack) => Text('Error: $err'),
+    );
+  }
+}
+```
+
+### Bloc Pattern
+```dart
+class UserBloc extends Bloc<UserEvent, UserState> {
+  UserBloc() : super(UserInitial()) {
+    on<LoadUser>(_onLoadUser);
+  }
+
+  Future<void> _onLoadUser(LoadUser event, Emitter<UserState> emit) async {
+    emit(UserLoading());
+    try {
+      final user = await repository.getUser(event.id);
+      emit(UserLoaded(user));
+    } catch (e) {
+      emit(UserError(e.toString()));
+    }
+  }
+}
+```
+
+## Navigation
+
+### Named Routes
+```dart
+// Define routes
+final routes = {
+  '/': (context) => HomeScreen(),
+  '/profile': (context) => ProfileScreen(),
+  '/settings': (context) => SettingsScreen(),
+};
+
+// Navigate
+Navigator.pushNamed(context, '/profile');
+
+// With arguments
+Navigator.pushNamed(
+  context,
+  '/profile',
+  arguments: {'userId': '123'},
+);
+```
+
+### Go Router (Modern)
+```dart
+final router = GoRouter(
+  routes: [
+    GoRoute(
+      path: '/',
+      builder: (context, state) => HomeScreen(),
+    ),
+    GoRoute(
+      path: '/profile/:id',
+      builder: (context, state) {
+        final id = state.pathParameters['id']!;
+        return ProfileScreen(userId: id);
+      },
+    ),
+  ],
+);
+
+// Navigate
+context.go('/profile/123');
+context.push('/settings');
+```
+
+## Performance Optimization
+
+### const Constructors
+```dart
+// Use const wherever possible
+const Text('Hello');
+const Padding(padding: EdgeInsets.all(8.0));
+const SizedBox(height: 16);
+```
+
+### ListView.builder
+```dart
+// For large lists, use builder
+ListView.builder(
+  itemCount: items.length,
+  itemBuilder: (context, index) {
+    return ListTile(title: Text(items[index]));
+  },
+);
+```
+
+### Keys
+```dart
+// Use keys for widgets that need to preserve state
+ListView(
+  children: items.map((item) => 
+    ListTile(
+      key: ValueKey(item.id),
+      title: Text(item.name),
+    )
+  ).toList(),
+);
+```
+
+## Responsive Design
+
+### MediaQuery
+```dart
+final size = MediaQuery.of(context).size;
+final isPortrait = size.height > size.width;
+
+if (size.width > 600) {
+  // Tablet layout
+} else {
+  // Mobile layout
+}
+```
+
+### LayoutBuilder
+```dart
+LayoutBuilder(
+  builder: (context, constraints) {
+    if (constraints.maxWidth > 600) {
+      return WideLayout();
+    }
+    return NarrowLayout();
+  },
+);
+```
+
+## Testing
+
+### Widget Tests
+```dart
+testWidgets('Counter increments', (tester) async {
+  await tester.pumpWidget(
+    MaterialApp(home: Counter()),
+  );
+
+  expect(find.text('0'), findsOneWidget);
+  
+  await tester.tap(find.byType(ElevatedButton));
+  await tester.pump();
+  
+  expect(find.text('1'), findsOneWidget);
+});
+```
+
+### Integration Tests
+```dart
+void main() {
+  IntegrationTestWidgetsFlutterBinding.ensureInitialized();
+
+  testWidgets('Complete user flow', (tester) async {
+    await tester.pumpWidget(MyApp());
+    
+    // Login
+    await tester.enterText(find.byKey(Key('email')), 'test@test.com');
+    await tester.tap(find.byKey(Key('login')));
+    await tester.pumpAndSettle();
+    
+    // Verify home screen
+    expect(find.text('Welcome'), findsOneWidget);
+  });
+}
+```
+
+## Best Practices
+
+### Widget Composition
+- Break large widgets into smaller, reusable components
+- Extract complex logic into separate methods or classes
+- Use const constructors to improve performance
+
+### Error Handling
+- Use ErrorWidget.builder for custom error widgets
+- Wrap risky operations in try-catch
+- Provide meaningful error messages to users
+
+### Asset Management
+```yaml
+# pubspec.yaml
+flutter:
+  assets:
+    - assets/images/
+    - assets/icons/
+  fonts:
+    - family: Roboto
+      fonts:
+        - asset: fonts/Roboto-Regular.ttf
+```
+
+### Platform-Specific Code
+```dart
+import 'dart:io' show Platform;
+
+if (Platform.isAndroid) {
+  // Android-specific
+} else if (Platform.isIOS) {
+  // iOS-specific
+}
+```
+
+## Common Patterns
+
+### Dependency Injection
+```dart
+class MyApp extends StatelessWidget {
+  final ApiService apiService;
+  final AuthService authService;
+
+  const MyApp({
+    required this.apiService,
+    required this.authService,
+  });
+}
+```
+
+### Service Locator
+```dart
+final getIt = GetIt.instance;
+
+void setupLocator() {
+  getIt.registerSingleton<ApiService>(ApiService());
+  getIt.registerLazySingleton<AuthService>(() => AuthService());
+}
+
+// Usage
+final api = getIt<ApiService>();
+```

package/dist/dart/templates/lang-dart.md

@@ -0,0 +1,233 @@
+# Dart Development Guidelines
+
+## Language Overview
+Dart is a client-optimized language for fast apps on any platform. It's the programming language behind Flutter and supports strong typing with null safety.
+
+## Code Style & Conventions
+
+### Naming
+- **Classes/Enums/Typedefs**: PascalCase (`UserModel`, `ColorState`)
+- **Functions/Variables**: camelCase (`getUserData`, `userName`)
+- **Constants**: lowerCamelCase (`defaultTimeout`, `maxRetries`)
+- **Private members**: Prefix with underscore (`_privateMethod`, `_internalState`)
+
+### Null Safety
+```dart
+// Non-nullable by default
+String name;  // Must be initialized
+String? optionalName;  // Can be null
+
+// Null-aware operators
+String? maybeValue;
+final length = maybeValue?.length ?? 0;  // Default value
+final value = maybeValue!;  // Null assertion (use carefully)
+```
+
+### Collections
+```dart
+// Use const for immutable collections
+const colors = ['red', 'green', 'blue'];
+
+// Type-safe collections
+final List<User> users = [];
+final Map<String, int> scores = {};
+final Set<String> uniqueNames = {};
+
+// Collection operators
+final adults = users.where((u) => u.age >= 18).toList();
+final names = users.map((u) => u.name).toList();
+```
+
+## Object-Oriented Programming
+
+### Classes
+```dart
+class User {
+  final String id;
+  final String name;
+  final int age;
+
+  // Constructor with named parameters
+  const User({
+    required this.id,
+    required this.name,
+    required this.age,
+  });
+
+  // Named constructor
+  User.guest() : this(id: 'guest', name: 'Guest', age: 0);
+
+  // Factory constructor
+  factory User.fromJson(Map<String, dynamic> json) {
+    return User(
+      id: json['id'],
+      name: json['name'],
+      age: json['age'],
+    );
+  }
+
+  // Copyhold
+  User copyWith({String? name, int? age}) {
+    return User(
+      id: id,
+      name: name ?? this.name,
+      age: age ?? this.age,
+    );
+  }
+}
+```
+
+### Mixins
+```dart
+mixin LoggerMixin {
+  void log(String message) {
+    print('[${DateTime.now()}] $message');
+  }
+}
+
+class MyService with LoggerMixin {
+  void doSomething() {
+    log('Doing something');
+  }
+}
+```
+
+## Async Programming
+
+### Futures
+```dart
+Future<User> fetchUser(String id) async {
+  final response = await http.get(Uri.parse('/users/$id'));
+  return User.fromJson(json.decode(response.body));
+}
+
+// Error handling
+try {
+  final user = await fetchUser('123');
+} catch (e) {
+  print('Error: $e');
+}
+```
+
+### Streams
+```dart
+Stream<int> countStream(int max) async* {
+  for (int i = 1; i <= max; i++) {
+    await Future.delayed(Duration(seconds: 1));
+    yield i;
+  }
+}
+
+// Usage
+await for (final count in countStream(5)) {
+  print(count);
+}
+```
+
+## Testing
+
+### Unit Tests
+```dart
+import 'package:test/test.dart';
+
+void main() {
+  group('User', () {
+    test('creates from JSON', () {
+      final json = {'id': '1', 'name': 'John', 'age': 30};
+      final user = User.fromJson(json);
+      
+      expect(user.id, '1');
+      expect(user.name, 'John');
+      expect(user.age, 30);
+    });
+
+    test('copyWith preserves unchanged fields', () {
+      final user = User(id: '1', name: 'John', age: 30);
+      final updated = user.copyWith(name: 'Jane');
+      
+      expect(updated.id, user.id);
+      expect(updated.name, 'Jane');
+      expect(updated.age, user.age);
+    });
+  });
+}
+```
+
+## Best Practices
+
+### Performance
+- Use `const` constructors when possible
+- Prefer `final` over `var` for immutability
+- Use collection literals instead of constructors
+- Avoid unnecessary rebuilds
+
+### Code Organization
+- One class per file (generally)
+- Group related files in directories
+- Use barrel files (index.dart) for clean exports
+- Separate models, services, and utilities
+
+### Error Handling
+- Use exceptions for exceptional cases
+- Return `Result<T, E>` types for expected failures
+- Validate input early
+- Provide meaningful error messages
+
+## Common Patterns
+
+### Singleton
+```dart
+class ApiService {
+  static final ApiService _instance = ApiService._internal();
+  factory ApiService() => _instance;
+  ApiService._internal();
+}
+```
+
+### Factory Pattern
+```dart
+abstract class Shape {
+  factory Shape(String type) {
+    switch (type) {
+      case 'circle':
+        return Circle();
+      case 'square':
+        return Square();
+      default:
+        throw ArgumentError('Unknown shape: $type');
+    }
+  }
+}
+```
+
+### Repository Pattern
+```dart
+abstract class UserRepository {
+  Future<User> getUser(String id);
+  Future<void> saveUser(User user);
+}
+
+class ApiUserRepository implements UserRepository {
+  @override
+  Future<User> getUser(String id) async {
+    // Implementation
+  }
+}
+```
+
+## Tools & Commands
+```bash
+# Format code
+dart format .
+
+# Analyze code
+dart analyze
+
+# Run tests
+dart test
+
+# Pub commands
+dart pub get
+dart pub upgrade
+dart pub outdated
+```

package/dist/elixir/templates/lang-elixir.md

@@ -0,0 +1,147 @@
+# Elixir Development Guidelines
+
+## Language Overview
+Elixir is a functional, concurrent programming language built on the Erlang VM (BEAM). It's designed for building scalable, maintainable applications with excellent support for distributed systems.
+
+## Code Style & Conventions
+
+### Naming
+- **Modules**: PascalCase (`MyApp.UserController`)
+- **Functions/Variables**: snake_case (`create_user`, `user_id`)
+- **Atoms**: snake_case (`:ok`, `:error`, `:user_not_found`)
+- **Constants**: snake_case module attributes (`@default_timeout`)
+
+### Pattern Matching
+```elixir
+# Use pattern matching extensively
+def process({:ok, result}), do: result
+def process({:error, reason}), do: Logger.error(reason)
+
+# Guards for additional constraints
+def divide(a, b) when b != 0, do: {:ok, a / b}
+def divide(_, 0), do: {:error, :division_by_zero}
+```
+
+### Pipe Operator
+```elixir
+# Chain operations with |>
+user
+|> validate_user()
+|> create_record()
+|> send_welcome_email()
+```
+
+## OTP Patterns
+
+### GenServer
+```elixir
+defmodule MyApp.Worker do
+  use GenServer
+
+  def start_link(opts) do
+    GenServer.start_link(__MODULE__, opts, name: __MODULE__)
+  end
+
+  def init(state) do
+    {:ok, state}
+  end
+
+  def handle_call({:get, key}, _from, state) do
+    {:reply, Map.get(state, key), state}
+  end
+end
+```
+
+### Supervision
+```elixir
+children = [
+  {MyApp.Repo, []},
+  {MyApp.Worker, []},
+  {Phoenix.PubSub, name: MyApp.PubSub}
+]
+
+Supervisor.start_link(children, strategy: :one_for_one)
+```
+
+## Phoenix Framework
+
+### Controllers
+```elixir
+defmodule MyAppWeb.UserController do
+  use MyAppWeb, :controller
+
+  def create(conn, %{"user" => user_params}) do
+    case Accounts.create_user(user_params) do
+      {:ok, user} ->
+        conn
+        |> put_status(:created)
+        |> render("show.json", user: user)
+
+      {:error, changeset} ->
+        conn
+        |> put_status(:unprocessable_entity)
+        |> render("error.json", changeset: changeset)
+    end
+  end
+end
+```
+
+### Contexts
+- Group related functionality in contexts
+- Keep controllers thin, business logic in contexts
+- Use Ecto changesets for validation
+
+## Ecto Database
+
+### Schemas
+```elixir
+defmodule MyApp.User do
+  use Ecto.Schema
+  import Ecto.Changeset
+
+  schema "users" do
+    field :email, :string
+    field :name, :string
+    has_many :posts, MyApp.Post
+
+    timestamps()
+  end
+
+  def changeset(user, attrs) do
+    user
+    |> cast(attrs, [:email, :name])
+    |> validate_required([:email])
+    |> validate_format(:email, ~r/@/)
+    |> unique_constraint(:email)
+  end
+end
+```
+
+## Testing
+
+### ExUnit
+```elixir
+defmodule MyApp.UserTest do
+  use MyApp.DataCase
+
+  test "creates user with valid attrs" do
+    attrs = %{email: "test@example.com", name: "Test"}
+    assert {:ok, user} = Accounts.create_user(attrs)
+    assert user.email == "test@example.com"
+  end
+end
+```
+
+## Error Handling
+- Use tagged tuples: `{:ok, result}`, `{:error, reason}`
+- Pattern match on results
+- Use `with` for complex error handling
+- Leverage supervisor restart strategies
+
+## Best Practices
+- Keep functions pure when possible
+- Use immutable data structures
+- Leverage concurrency with Task and GenServer
+- Follow "let it crash" philosophy
+- Use telemetry for observability
+- Run `mix format` before committing