@heyai-rules/pilo-masterkit 1.2.2 → 3.1.0

package/.agent/rules/dart/testing.md

@@ -0,0 +1,215 @@
+---
+paths:
+  - "**/*.dart"
+  - "**/pubspec.yaml"
+  - "**/analysis_options.yaml"
+---
+# Dart/Flutter Testing
+
+> This file extends [common/testing.md](../common/testing.md) with Dart and Flutter-specific content.
+
+## Test Framework
+
+- **flutter_test** / **dart:test** — built-in test runner
+- **mockito** (with `@GenerateMocks`) or **mocktail** (no codegen) for mocking
+- **bloc_test** for BLoC/Cubit unit tests
+- **fake_async** for controlling time in unit tests
+- **integration_test** for end-to-end device tests
+
+## Test Types
+
+| Type | Tool | Location | When to Write |
+|------|------|----------|---------------|
+| Unit | `dart:test` | `test/unit/` | All domain logic, state managers, repositories |
+| Widget | `flutter_test` | `test/widget/` | All widgets with meaningful behavior |
+| Golden | `flutter_test` | `test/golden/` | Design-critical UI components |
+| Integration | `integration_test` | `integration_test/` | Critical user flows on real device/emulator |
+
+## Unit Tests: State Managers
+
+### BLoC with `bloc_test`
+
+```dart
+group('CartBloc', () {
+  late CartBloc bloc;
+  late MockCartRepository repository;
+
+  setUp(() {
+    repository = MockCartRepository();
+    bloc = CartBloc(repository);
+  });
+
+  tearDown(() => bloc.close());
+
+  blocTest<CartBloc, CartState>(
+    'emits updated items when CartItemAdded',
+    build: () => bloc,
+    act: (b) => b.add(CartItemAdded(testItem)),
+    expect: () => [CartState(items: [testItem])],
+  );
+
+  blocTest<CartBloc, CartState>(
+    'emits empty cart when CartCleared',
+    seed: () => CartState(items: [testItem]),
+    build: () => bloc,
+    act: (b) => b.add(CartCleared()),
+    expect: () => [const CartState()],
+  );
+});
+```
+
+### Riverpod with `ProviderContainer`
+
+```dart
+test('usersProvider loads users from repository', () async {
+  final container = ProviderContainer(
+    overrides: [userRepositoryProvider.overrideWithValue(FakeUserRepository())],
+  );
+  addTearDown(container.dispose);
+
+  final result = await container.read(usersProvider.future);
+  expect(result, isNotEmpty);
+});
+```
+
+## Widget Tests
+
+```dart
+testWidgets('CartPage shows item count badge', (tester) async {
+  await tester.pumpWidget(
+    ProviderScope(
+      overrides: [
+        cartNotifierProvider.overrideWith(() => FakeCartNotifier([testItem])),
+      ],
+      child: const MaterialApp(home: CartPage()),
+    ),
+  );
+
+  await tester.pump();
+  expect(find.text('1'), findsOneWidget);
+  expect(find.byType(CartItemTile), findsOneWidget);
+});
+
+testWidgets('shows empty state when cart is empty', (tester) async {
+  await tester.pumpWidget(
+    ProviderScope(
+      overrides: [cartNotifierProvider.overrideWith(() => FakeCartNotifier([]))],
+      child: const MaterialApp(home: CartPage()),
+    ),
+  );
+
+  await tester.pump();
+  expect(find.text('Your cart is empty'), findsOneWidget);
+});
+```
+
+## Fakes Over Mocks
+
+Prefer hand-written fakes for complex dependencies:
+
+```dart
+class FakeUserRepository implements UserRepository {
+  final _users = <String, User>{};
+  Object? fetchError;
+
+  @override
+  Future<User?> getById(String id) async {
+    if (fetchError != null) throw fetchError!;
+    return _users[id];
+  }
+
+  @override
+  Future<List<User>> getAll() async {
+    if (fetchError != null) throw fetchError!;
+    return _users.values.toList();
+  }
+
+  @override
+  Stream<List<User>> watchAll() => Stream.value(_users.values.toList());
+
+  @override
+  Future<void> save(User user) async {
+    _users[user.id] = user;
+  }
+
+  @override
+  Future<void> delete(String id) async {
+    _users.remove(id);
+  }
+
+  void addUser(User user) => _users[user.id] = user;
+}
+```
+
+## Async Testing
+
+```dart
+// Use fake_async for controlling timers and Futures
+test('debounce triggers after 300ms', () {
+  fakeAsync((async) {
+    final debouncer = Debouncer(delay: const Duration(milliseconds: 300));
+    var callCount = 0;
+    debouncer.run(() => callCount++);
+    expect(callCount, 0);
+    async.elapse(const Duration(milliseconds: 200));
+    expect(callCount, 0);
+    async.elapse(const Duration(milliseconds: 200));
+    expect(callCount, 1);
+  });
+});
+```
+
+## Golden Tests
+
+```dart
+testWidgets('UserCard golden test', (tester) async {
+  await tester.pumpWidget(
+    MaterialApp(home: UserCard(user: testUser)),
+  );
+
+  await expectLater(
+    find.byType(UserCard),
+    matchesGoldenFile('goldens/user_card.png'),
+  );
+});
+```
+
+Run `flutter test --update-goldens` when intentional visual changes are made.
+
+## Test Naming
+
+Use descriptive, behavior-focused names:
+
+```dart
+test('returns null when user does not exist', () { ... });
+test('throws NotFoundException when id is empty string', () { ... });
+testWidgets('disables submit button while form is invalid', (tester) async { ... });
+```
+
+## Test Organization
+
+```
+test/
+├── unit/
+│   ├── domain/
+│   │   └── usecases/
+│   └── data/
+│       └── repositories/
+├── widget/
+│   └── presentation/
+│       └── pages/
+└── golden/
+    └── widgets/
+
+integration_test/
+└── flows/
+    ├── login_flow_test.dart
+    └── checkout_flow_test.dart
+```
+
+## Coverage
+
+- Target 80%+ line coverage for business logic (domain + state managers)
+- All state transitions must have tests: loading → success, loading → error, retry
+- Run `flutter test --coverage` and inspect `lcov.info` with a coverage reporter
+- Coverage failures should block CI when below threshold

package/.agent/rules/golang/coding-style.md

@@ -0,0 +1,32 @@
+---
+paths:
+  - "**/*.go"
+  - "**/go.mod"
+  - "**/go.sum"
+---
+# Go Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with Go specific content.
+
+## Formatting
+
+- **gofmt** and **goimports** are mandatory — no style debates
+
+## Design Principles
+
+- Accept interfaces, return structs
+- Keep interfaces small (1-3 methods)
+
+## Error Handling
+
+Always wrap errors with context:
+
+```go
+if err != nil {
+    return fmt.Errorf("failed to create user: %w", err)
+}
+```
+
+## Reference
+
+See skill: `golang-patterns` for comprehensive Go idioms and patterns.

package/.agent/rules/golang/hooks.md

@@ -0,0 +1,17 @@
+---
+paths:
+  - "**/*.go"
+  - "**/go.mod"
+  - "**/go.sum"
+---
+# Go Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with Go specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **gofmt/goimports**: Auto-format `.go` files after edit
+- **go vet**: Run static analysis after editing `.go` files
+- **staticcheck**: Run extended static checks on modified packages

package/.agent/rules/golang/patterns.md

@@ -0,0 +1,45 @@
+---
+paths:
+  - "**/*.go"
+  - "**/go.mod"
+  - "**/go.sum"
+---
+# Go Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with Go specific content.
+
+## Functional Options
+
+```go
+type Option func(*Server)
+
+func WithPort(port int) Option {
+    return func(s *Server) { s.port = port }
+}
+
+func NewServer(opts ...Option) *Server {
+    s := &Server{port: 8080}
+    for _, opt := range opts {
+        opt(s)
+    }
+    return s
+}
+```
+
+## Small Interfaces
+
+Define interfaces where they are used, not where they are implemented.
+
+## Dependency Injection
+
+Use constructor functions to inject dependencies:
+
+```go
+func NewUserService(repo UserRepository, logger Logger) *UserService {
+    return &UserService{repo: repo, logger: logger}
+}
+```
+
+## Reference
+
+See skill: `golang-patterns` for comprehensive Go patterns including concurrency, error handling, and package organization.

package/.agent/rules/golang/security.md

@@ -0,0 +1,34 @@
+---
+paths:
+  - "**/*.go"
+  - "**/go.mod"
+  - "**/go.sum"
+---
+# Go Security
+
+> This file extends [common/security.md](../common/security.md) with Go specific content.
+
+## Secret Management
+
+```go
+apiKey := os.Getenv("OPENAI_API_KEY")
+if apiKey == "" {
+    log.Fatal("OPENAI_API_KEY not configured")
+}
+```
+
+## Security Scanning
+
+- Use **gosec** for static security analysis:
+  ```bash
+  gosec ./...
+  ```
+
+## Context & Timeouts
+
+Always use `context.Context` for timeout control:
+
+```go
+ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+defer cancel()
+```

package/.agent/rules/golang/testing.md

@@ -0,0 +1,31 @@
+---
+paths:
+  - "**/*.go"
+  - "**/go.mod"
+  - "**/go.sum"
+---
+# Go Testing
+
+> This file extends [common/testing.md](../common/testing.md) with Go specific content.
+
+## Framework
+
+Use the standard `go test` with **table-driven tests**.
+
+## Race Detection
+
+Always run with the `-race` flag:
+
+```bash
+go test -race ./...
+```
+
+## Coverage
+
+```bash
+go test -cover ./...
+```
+
+## Reference
+
+See skill: `golang-testing` for detailed Go testing patterns and helpers.

package/.agent/rules/java/coding-style.md

@@ -0,0 +1,114 @@
+---
+paths:
+  - "**/*.java"
+---
+# Java Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with Java-specific content.
+
+## Formatting
+
+- **google-java-format** or **Checkstyle** (Google or Sun style) for enforcement
+- One public top-level type per file
+- Consistent indent: 2 or 4 spaces (match project standard)
+- Member order: constants, fields, constructors, public methods, protected, private
+
+## Immutability
+
+- Prefer `record` for value types (Java 16+)
+- Mark fields `final` by default — use mutable state only when required
+- Return defensive copies from public APIs: `List.copyOf()`, `Map.copyOf()`, `Set.copyOf()`
+- Copy-on-write: return new instances rather than mutating existing ones
+
+```java
+// GOOD — immutable value type
+public record OrderSummary(Long id, String customerName, BigDecimal total) {}
+
+// GOOD — final fields, no setters
+public class Order {
+    private final Long id;
+    private final List<LineItem> items;
+
+    public List<LineItem> getItems() {
+        return List.copyOf(items);
+    }
+}
+```
+
+## Naming
+
+Follow standard Java conventions:
+- `PascalCase` for classes, interfaces, records, enums
+- `camelCase` for methods, fields, parameters, local variables
+- `SCREAMING_SNAKE_CASE` for `static final` constants
+- Packages: all lowercase, reverse domain (`com.example.app.service`)
+
+## Modern Java Features
+
+Use modern language features where they improve clarity:
+- **Records** for DTOs and value types (Java 16+)
+- **Sealed classes** for closed type hierarchies (Java 17+)
+- **Pattern matching** with `instanceof` — no explicit cast (Java 16+)
+- **Text blocks** for multi-line strings — SQL, JSON templates (Java 15+)
+- **Switch expressions** with arrow syntax (Java 14+)
+- **Pattern matching in switch** — exhaustive sealed type handling (Java 21+)
+
+```java
+// Pattern matching instanceof
+if (shape instanceof Circle c) {
+    return Math.PI * c.radius() * c.radius();
+}
+
+// Sealed type hierarchy
+public sealed interface PaymentMethod permits CreditCard, BankTransfer, Wallet {}
+
+// Switch expression
+String label = switch (status) {
+    case ACTIVE -> "Active";
+    case SUSPENDED -> "Suspended";
+    case CLOSED -> "Closed";
+};
+```
+
+## Optional Usage
+
+- Return `Optional<T>` from finder methods that may have no result
+- Use `map()`, `flatMap()`, `orElseThrow()` — never call `get()` without `isPresent()`
+- Never use `Optional` as a field type or method parameter
+
+```java
+// GOOD
+return repository.findById(id)
+    .map(ResponseDto::from)
+    .orElseThrow(() -> new OrderNotFoundException(id));
+
+// BAD — Optional as parameter
+public void process(Optional<String> name) {}
+```
+
+## Error Handling
+
+- Prefer unchecked exceptions for domain errors
+- Create domain-specific exceptions extending `RuntimeException`
+- Avoid broad `catch (Exception e)` unless at top-level handlers
+- Include context in exception messages
+
+```java
+public class OrderNotFoundException extends RuntimeException {
+    public OrderNotFoundException(Long id) {
+        super("Order not found: id=" + id);
+    }
+}
+```
+
+## Streams
+
+- Use streams for transformations; keep pipelines short (3-4 operations max)
+- Prefer method references when readable: `.map(Order::getTotal)`
+- Avoid side effects in stream operations
+- For complex logic, prefer a loop over a convoluted stream pipeline
+
+## References
+
+See skill: `java-coding-standards` for full coding standards with examples.
+See skill: `jpa-patterns` for JPA/Hibernate entity design patterns.

package/.agent/rules/java/hooks.md

@@ -0,0 +1,18 @@
+---
+paths:
+  - "**/*.java"
+  - "**/pom.xml"
+  - "**/build.gradle"
+  - "**/build.gradle.kts"
+---
+# Java Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with Java-specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **google-java-format**: Auto-format `.java` files after edit
+- **checkstyle**: Run style checks after editing Java files
+- **./mvnw compile** or **./gradlew compileJava**: Verify compilation after changes

package/.agent/rules/java/patterns.md

@@ -0,0 +1,146 @@
+---
+paths:
+  - "**/*.java"
+---
+# Java Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with Java-specific content.
+
+## Repository Pattern
+
+Encapsulate data access behind an interface:
+
+```java
+public interface OrderRepository {
+    Optional<Order> findById(Long id);
+    List<Order> findAll();
+    Order save(Order order);
+    void deleteById(Long id);
+}
+```
+
+Concrete implementations handle storage details (JPA, JDBC, in-memory for tests).
+
+## Service Layer
+
+Business logic in service classes; keep controllers and repositories thin:
+
+```java
+public class OrderService {
+    private final OrderRepository orderRepository;
+    private final PaymentGateway paymentGateway;
+
+    public OrderService(OrderRepository orderRepository, PaymentGateway paymentGateway) {
+        this.orderRepository = orderRepository;
+        this.paymentGateway = paymentGateway;
+    }
+
+    public OrderSummary placeOrder(CreateOrderRequest request) {
+        var order = Order.from(request);
+        paymentGateway.charge(order.total());
+        var saved = orderRepository.save(order);
+        return OrderSummary.from(saved);
+    }
+}
+```
+
+## Constructor Injection
+
+Always use constructor injection — never field injection:
+
+```java
+// GOOD — constructor injection (testable, immutable)
+public class NotificationService {
+    private final EmailSender emailSender;
+
+    public NotificationService(EmailSender emailSender) {
+        this.emailSender = emailSender;
+    }
+}
+
+// BAD — field injection (untestable without reflection, requires framework magic)
+public class NotificationService {
+    @Inject // or @Autowired
+    private EmailSender emailSender;
+}
+```
+
+## DTO Mapping
+
+Use records for DTOs. Map at service/controller boundaries:
+
+```java
+public record OrderResponse(Long id, String customer, BigDecimal total) {
+    public static OrderResponse from(Order order) {
+        return new OrderResponse(order.getId(), order.getCustomerName(), order.getTotal());
+    }
+}
+```
+
+## Builder Pattern
+
+Use for objects with many optional parameters:
+
+```java
+public class SearchCriteria {
+    private final String query;
+    private final int page;
+    private final int size;
+    private final String sortBy;
+
+    private SearchCriteria(Builder builder) {
+        this.query = builder.query;
+        this.page = builder.page;
+        this.size = builder.size;
+        this.sortBy = builder.sortBy;
+    }
+
+    public static class Builder {
+        private String query = "";
+        private int page = 0;
+        private int size = 20;
+        private String sortBy = "id";
+
+        public Builder query(String query) { this.query = query; return this; }
+        public Builder page(int page) { this.page = page; return this; }
+        public Builder size(int size) { this.size = size; return this; }
+        public Builder sortBy(String sortBy) { this.sortBy = sortBy; return this; }
+        public SearchCriteria build() { return new SearchCriteria(this); }
+    }
+}
+```
+
+## Sealed Types for Domain Models
+
+```java
+public sealed interface PaymentResult permits PaymentSuccess, PaymentFailure {
+    record PaymentSuccess(String transactionId, BigDecimal amount) implements PaymentResult {}
+    record PaymentFailure(String errorCode, String message) implements PaymentResult {}
+}
+
+// Exhaustive handling (Java 21+)
+String message = switch (result) {
+    case PaymentSuccess s -> "Paid: " + s.transactionId();
+    case PaymentFailure f -> "Failed: " + f.errorCode();
+};
+```
+
+## API Response Envelope
+
+Consistent API responses:
+
+```java
+public record ApiResponse<T>(boolean success, T data, String error) {
+    public static <T> ApiResponse<T> ok(T data) {
+        return new ApiResponse<>(true, data, null);
+    }
+    public static <T> ApiResponse<T> error(String message) {
+        return new ApiResponse<>(false, null, message);
+    }
+}
+```
+
+## References
+
+See skill: `springboot-patterns` for Spring Boot architecture patterns.
+See skill: `jpa-patterns` for entity design and query optimization.