@heyai-rules/pilo-masterkit 1.2.2 → 2.1.0

package/.agent/rules/kotlin/patterns.md

@@ -0,0 +1,146 @@
+---
+paths:
+  - "**/*.kt"
+  - "**/*.kts"
+---
+# Kotlin Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with Kotlin and Android/KMP-specific content.
+
+## Dependency Injection
+
+Prefer constructor injection. Use Koin (KMP) or Hilt (Android-only):
+
+```kotlin
+// Koin — declare modules
+val dataModule = module {
+    single<ItemRepository> { ItemRepositoryImpl(get(), get()) }
+    factory { GetItemsUseCase(get()) }
+    viewModelOf(::ItemListViewModel)
+}
+
+// Hilt — annotations
+@HiltViewModel
+class ItemListViewModel @Inject constructor(
+    private val getItems: GetItemsUseCase
+) : ViewModel()
+```
+
+## ViewModel Pattern
+
+Single state object, event sink, one-way data flow:
+
+```kotlin
+data class ScreenState(
+    val items: List<Item> = emptyList(),
+    val isLoading: Boolean = false
+)
+
+class ScreenViewModel(private val useCase: GetItemsUseCase) : ViewModel() {
+    private val _state = MutableStateFlow(ScreenState())
+    val state = _state.asStateFlow()
+
+    fun onEvent(event: ScreenEvent) {
+        when (event) {
+            is ScreenEvent.Load -> load()
+            is ScreenEvent.Delete -> delete(event.id)
+        }
+    }
+}
+```
+
+## Repository Pattern
+
+- `suspend` functions return `Result<T>` or custom error type
+- `Flow` for reactive streams
+- Coordinate local + remote data sources
+
+```kotlin
+interface ItemRepository {
+    suspend fun getById(id: String): Result<Item>
+    suspend fun getAll(): Result<List<Item>>
+    fun observeAll(): Flow<List<Item>>
+}
+```
+
+## UseCase Pattern
+
+Single responsibility, `operator fun invoke`:
+
+```kotlin
+class GetItemUseCase(private val repository: ItemRepository) {
+    suspend operator fun invoke(id: String): Result<Item> {
+        return repository.getById(id)
+    }
+}
+
+class GetItemsUseCase(private val repository: ItemRepository) {
+    suspend operator fun invoke(): Result<List<Item>> {
+        return repository.getAll()
+    }
+}
+```
+
+## expect/actual (KMP)
+
+Use for platform-specific implementations:
+
+```kotlin
+// commonMain
+expect fun platformName(): String
+expect class SecureStorage {
+    fun save(key: String, value: String)
+    fun get(key: String): String?
+}
+
+// androidMain
+actual fun platformName(): String = "Android"
+actual class SecureStorage {
+    actual fun save(key: String, value: String) { /* EncryptedSharedPreferences */ }
+    actual fun get(key: String): String? = null /* ... */
+}
+
+// iosMain
+actual fun platformName(): String = "iOS"
+actual class SecureStorage {
+    actual fun save(key: String, value: String) { /* Keychain */ }
+    actual fun get(key: String): String? = null /* ... */
+}
+```
+
+## Coroutine Patterns
+
+- Use `viewModelScope` in ViewModels, `coroutineScope` for structured child work
+- Use `stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), initialValue)` for StateFlow from cold Flows
+- Use `supervisorScope` when child failures should be independent
+
+## Builder Pattern with DSL
+
+```kotlin
+class HttpClientConfig {
+    var baseUrl: String = ""
+    var timeout: Long = 30_000
+    private val interceptors = mutableListOf<Interceptor>()
+
+    fun interceptor(block: () -> Interceptor) {
+        interceptors.add(block())
+    }
+}
+
+fun httpClient(block: HttpClientConfig.() -> Unit): HttpClient {
+    val config = HttpClientConfig().apply(block)
+    return HttpClient(config)
+}
+
+// Usage
+val client = httpClient {
+    baseUrl = "https://api.example.com"
+    timeout = 15_000
+    interceptor { AuthInterceptor(tokenProvider) }
+}
+```
+
+## References
+
+See skill: `kotlin-coroutines-flows` for detailed coroutine patterns.
+See skill: `android-clean-architecture` for module and layer patterns.

package/.agent/rules/kotlin/security.md

@@ -0,0 +1,82 @@
+---
+paths:
+  - "**/*.kt"
+  - "**/*.kts"
+---
+# Kotlin Security
+
+> This file extends [common/security.md](../common/security.md) with Kotlin and Android/KMP-specific content.
+
+## Secrets Management
+
+- Never hardcode API keys, tokens, or credentials in source code
+- Use `local.properties` (git-ignored) for local development secrets
+- Use `BuildConfig` fields generated from CI secrets for release builds
+- Use `EncryptedSharedPreferences` (Android) or Keychain (iOS) for runtime secret storage
+
+```kotlin
+// BAD
+val apiKey = "sk-abc123..."
+
+// GOOD — from BuildConfig (generated at build time)
+val apiKey = BuildConfig.API_KEY
+
+// GOOD — from secure storage at runtime
+val token = secureStorage.get("auth_token")
+```
+
+## Network Security
+
+- Use HTTPS exclusively — configure `network_security_config.xml` to block cleartext
+- Pin certificates for sensitive endpoints using OkHttp `CertificatePinner` or Ktor equivalent
+- Set timeouts on all HTTP clients — never leave defaults (which may be infinite)
+- Validate and sanitize all server responses before use
+
+```xml
+<!-- res/xml/network_security_config.xml -->
+<network-security-config>
+    <base-config cleartextTrafficPermitted="false" />
+</network-security-config>
+```
+
+## Input Validation
+
+- Validate all user input before processing or sending to API
+- Use parameterized queries for Room/SQLDelight — never concatenate user input into SQL
+- Sanitize file paths from user input to prevent path traversal
+
+```kotlin
+// BAD — SQL injection
+@Query("SELECT * FROM items WHERE name = '$input'")
+
+// GOOD — parameterized
+@Query("SELECT * FROM items WHERE name = :input")
+fun findByName(input: String): List<ItemEntity>
+```
+
+## Data Protection
+
+- Use `EncryptedSharedPreferences` for sensitive key-value data on Android
+- Use `@Serializable` with explicit field names — don't leak internal property names
+- Clear sensitive data from memory when no longer needed
+- Use `@Keep` or ProGuard rules for serialized classes to prevent name mangling
+
+## Authentication
+
+- Store tokens in secure storage, not in plain SharedPreferences
+- Implement token refresh with proper 401/403 handling
+- Clear all auth state on logout (tokens, cached user data, cookies)
+- Use biometric authentication (`BiometricPrompt`) for sensitive operations
+
+## ProGuard / R8
+
+- Keep rules for all serialized models (`@Serializable`, Gson, Moshi)
+- Keep rules for reflection-based libraries (Koin, Retrofit)
+- Test release builds — obfuscation can break serialization silently
+
+## WebView Security
+
+- Disable JavaScript unless explicitly needed: `settings.javaScriptEnabled = false`
+- Validate URLs before loading in WebView
+- Never expose `@JavascriptInterface` methods that access sensitive data
+- Use `WebViewClient.shouldOverrideUrlLoading()` to control navigation

package/.agent/rules/kotlin/testing.md

@@ -0,0 +1,128 @@
+---
+paths:
+  - "**/*.kt"
+  - "**/*.kts"
+---
+# Kotlin Testing
+
+> This file extends [common/testing.md](../common/testing.md) with Kotlin and Android/KMP-specific content.
+
+## Test Framework
+
+- **kotlin.test** for multiplatform (KMP) — `@Test`, `assertEquals`, `assertTrue`
+- **JUnit 4/5** for Android-specific tests
+- **Turbine** for testing Flows and StateFlow
+- **kotlinx-coroutines-test** for coroutine testing (`runTest`, `TestDispatcher`)
+
+## ViewModel Testing with Turbine
+
+```kotlin
+@Test
+fun `loading state emitted then data`() = runTest {
+    val repo = FakeItemRepository()
+    repo.addItem(testItem)
+    val viewModel = ItemListViewModel(GetItemsUseCase(repo))
+
+    viewModel.state.test {
+        assertEquals(ItemListState(), awaitItem())     // initial state
+        viewModel.onEvent(ItemListEvent.Load)
+        assertTrue(awaitItem().isLoading)               // loading
+        assertEquals(listOf(testItem), awaitItem().items) // loaded
+    }
+}
+```
+
+## Fakes Over Mocks
+
+Prefer hand-written fakes over mocking frameworks:
+
+```kotlin
+class FakeItemRepository : ItemRepository {
+    private val items = mutableListOf<Item>()
+    var fetchError: Throwable? = null
+
+    override suspend fun getAll(): Result<List<Item>> {
+        fetchError?.let { return Result.failure(it) }
+        return Result.success(items.toList())
+    }
+
+    override fun observeAll(): Flow<List<Item>> = flowOf(items.toList())
+
+    fun addItem(item: Item) { items.add(item) }
+}
+```
+
+## Coroutine Testing
+
+```kotlin
+@Test
+fun `parallel operations complete`() = runTest {
+    val repo = FakeRepository()
+    val result = loadDashboard(repo)
+    advanceUntilIdle()
+    assertNotNull(result.items)
+    assertNotNull(result.stats)
+}
+```
+
+Use `runTest` — it auto-advances virtual time and provides `TestScope`.
+
+## Ktor MockEngine
+
+```kotlin
+val mockEngine = MockEngine { request ->
+    when (request.url.encodedPath) {
+        "/api/items" -> respond(
+            content = Json.encodeToString(testItems),
+            headers = headersOf(HttpHeaders.ContentType, ContentType.Application.Json.toString())
+        )
+        else -> respondError(HttpStatusCode.NotFound)
+    }
+}
+
+val client = HttpClient(mockEngine) {
+    install(ContentNegotiation) { json() }
+}
+```
+
+## Room/SQLDelight Testing
+
+- Room: Use `Room.inMemoryDatabaseBuilder()` for in-memory testing
+- SQLDelight: Use `JdbcSqliteDriver(JdbcSqliteDriver.IN_MEMORY)` for JVM tests
+
+```kotlin
+@Test
+fun `insert and query items`() = runTest {
+    val driver = JdbcSqliteDriver(JdbcSqliteDriver.IN_MEMORY)
+    Database.Schema.create(driver)
+    val db = Database(driver)
+
+    db.itemQueries.insert("1", "Sample Item", "description")
+    val items = db.itemQueries.getAll().executeAsList()
+    assertEquals(1, items.size)
+}
+```
+
+## Test Naming
+
+Use backtick-quoted descriptive names:
+
+```kotlin
+@Test
+fun `search with empty query returns all items`() = runTest { }
+
+@Test
+fun `delete item emits updated list without deleted item`() = runTest { }
+```
+
+## Test Organization
+
+```
+src/
+├── commonTest/kotlin/     # Shared tests (ViewModel, UseCase, Repository)
+├── androidUnitTest/kotlin/ # Android unit tests (JUnit)
+├── androidInstrumentedTest/kotlin/  # Instrumented tests (Room, UI)
+└── iosTest/kotlin/        # iOS-specific tests
+```
+
+Minimum test coverage: ViewModel + UseCase for every feature.

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

@@ -0,0 +1,46 @@
+---
+paths:
+  - "**/*.pl"
+  - "**/*.pm"
+  - "**/*.t"
+  - "**/*.psgi"
+  - "**/*.cgi"
+---
+# Perl Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with Perl-specific content.
+
+## Standards
+
+- Always `use v5.36` (enables `strict`, `warnings`, `say`, subroutine signatures)
+- Use subroutine signatures — never unpack `@_` manually
+- Prefer `say` over `print` with explicit newlines
+
+## Immutability
+
+- Use **Moo** with `is => 'ro'` and `Types::Standard` for all attributes
+- Never use blessed hashrefs directly — always use Moo/Moose accessors
+- **OO override note**: Moo `has` attributes with `builder` or `default` are acceptable for computed read-only values
+
+## Formatting
+
+Use **perltidy** with these settings:
+
+```
+-i=4    # 4-space indent
+-l=100  # 100 char line length
+-ce     # cuddled else
+-bar    # opening brace always right
+```
+
+## Linting
+
+Use **perlcritic** at severity 3 with themes: `core`, `pbp`, `security`.
+
+```bash
+perlcritic --severity 3 --theme 'core || pbp || security' lib/
+```
+
+## Reference
+
+See skill: `perl-patterns` for comprehensive modern Perl idioms and best practices.

package/.agent/rules/perl/hooks.md

@@ -0,0 +1,22 @@
+---
+paths:
+  - "**/*.pl"
+  - "**/*.pm"
+  - "**/*.t"
+  - "**/*.psgi"
+  - "**/*.cgi"
+---
+# Perl Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with Perl-specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **perltidy**: Auto-format `.pl` and `.pm` files after edit
+- **perlcritic**: Run lint check after editing `.pm` files
+
+## Warnings
+
+- Warn about `print` in non-script `.pm` files — use `say` or a logging module (e.g., `Log::Any`)

package/.agent/rules/perl/patterns.md

@@ -0,0 +1,76 @@
+---
+paths:
+  - "**/*.pl"
+  - "**/*.pm"
+  - "**/*.t"
+  - "**/*.psgi"
+  - "**/*.cgi"
+---
+# Perl Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with Perl-specific content.
+
+## Repository Pattern
+
+Use **DBI** or **DBIx::Class** behind an interface:
+
+```perl
+package MyApp::Repo::User;
+use Moo;
+
+has dbh => (is => 'ro', required => 1);
+
+sub find_by_id ($self, $id) {
+    my $sth = $self->dbh->prepare('SELECT * FROM users WHERE id = ?');
+    $sth->execute($id);
+    return $sth->fetchrow_hashref;
+}
+```
+
+## DTOs / Value Objects
+
+Use **Moo** classes with **Types::Standard** (equivalent to Python dataclasses):
+
+```perl
+package MyApp::DTO::User;
+use Moo;
+use Types::Standard qw(Str Int);
+
+has name  => (is => 'ro', isa => Str, required => 1);
+has email => (is => 'ro', isa => Str, required => 1);
+has age   => (is => 'ro', isa => Int);
+```
+
+## Resource Management
+
+- Always use **three-arg open** with `autodie`
+- Use **Path::Tiny** for file operations
+
+```perl
+use autodie;
+use Path::Tiny;
+
+my $content = path('config.json')->slurp_utf8;
+```
+
+## Module Interface
+
+Use `Exporter 'import'` with `@EXPORT_OK` — never `@EXPORT`:
+
+```perl
+use Exporter 'import';
+our @EXPORT_OK = qw(parse_config validate_input);
+```
+
+## Dependency Management
+
+Use **cpanfile** + **carton** for reproducible installs:
+
+```bash
+carton install
+carton exec prove -lr t/
+```
+
+## Reference
+
+See skill: `perl-patterns` for comprehensive modern Perl patterns and idioms.

package/.agent/rules/perl/security.md

@@ -0,0 +1,69 @@
+---
+paths:
+  - "**/*.pl"
+  - "**/*.pm"
+  - "**/*.t"
+  - "**/*.psgi"
+  - "**/*.cgi"
+---
+# Perl Security
+
+> This file extends [common/security.md](../common/security.md) with Perl-specific content.
+
+## Taint Mode
+
+- Use `-T` flag on all CGI/web-facing scripts
+- Sanitize `%ENV` (`$ENV{PATH}`, `$ENV{CDPATH}`, etc.) before any external command
+
+## Input Validation
+
+- Use allowlist regex for untainting — never `/(.*)/s`
+- Validate all user input with explicit patterns:
+
+```perl
+if ($input =~ /\A([a-zA-Z0-9_-]+)\z/) {
+    my $clean = $1;
+}
+```
+
+## File I/O
+
+- **Three-arg open only** — never two-arg open
+- Prevent path traversal with `Cwd::realpath`:
+
+```perl
+use Cwd 'realpath';
+my $safe_path = realpath($user_path);
+die "Path traversal" unless $safe_path =~ m{\A/allowed/directory/};
+```
+
+## Process Execution
+
+- Use **list-form `system()`** — never single-string form
+- Use **IPC::Run3** for capturing output
+- Never use backticks with variable interpolation
+
+```perl
+system('grep', '-r', $pattern, $directory);  # safe
+```
+
+## SQL Injection Prevention
+
+Always use DBI placeholders — never interpolate into SQL:
+
+```perl
+my $sth = $dbh->prepare('SELECT * FROM users WHERE email = ?');
+$sth->execute($email);
+```
+
+## Security Scanning
+
+Run **perlcritic** with the security theme at severity 4+:
+
+```bash
+perlcritic --severity 4 --theme security lib/
+```
+
+## Reference
+
+See skill: `perl-security` for comprehensive Perl security patterns, taint mode, and safe I/O.

package/.agent/rules/perl/testing.md

@@ -0,0 +1,54 @@
+---
+paths:
+  - "**/*.pl"
+  - "**/*.pm"
+  - "**/*.t"
+  - "**/*.psgi"
+  - "**/*.cgi"
+---
+# Perl Testing
+
+> This file extends [common/testing.md](../common/testing.md) with Perl-specific content.
+
+## Framework
+
+Use **Test2::V0** for new projects (not Test::More):
+
+```perl
+use Test2::V0;
+
+is($result, 42, 'answer is correct');
+
+done_testing;
+```
+
+## Runner
+
+```bash
+prove -l t/              # adds lib/ to @INC
+prove -lr -j8 t/         # recursive, 8 parallel jobs
+```
+
+Always use `-l` to ensure `lib/` is on `@INC`.
+
+## Coverage
+
+Use **Devel::Cover** — target 80%+:
+
+```bash
+cover -test
+```
+
+## Mocking
+
+- **Test::MockModule** — mock methods on existing modules
+- **Test::MockObject** — create test doubles from scratch
+
+## Pitfalls
+
+- Always end test files with `done_testing`
+- Never forget the `-l` flag with `prove`
+
+## Reference
+
+See skill: `perl-testing` for detailed Perl TDD patterns with Test2::V0, prove, and Devel::Cover.

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

@@ -0,0 +1,40 @@
+---
+paths:
+  - "**/*.php"
+  - "**/composer.json"
+---
+# PHP Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with PHP specific content.
+
+## Standards
+
+- Follow **PSR-12** formatting and naming conventions.
+- Prefer `declare(strict_types=1);` in application code.
+- Use scalar type hints, return types, and typed properties everywhere new code permits.
+
+## Immutability
+
+- Prefer immutable DTOs and value objects for data crossing service boundaries.
+- Use `readonly` properties or immutable constructors for request/response payloads where possible.
+- Keep arrays for simple maps; promote business-critical structures into explicit classes.
+
+## Formatting
+
+- Use **PHP-CS-Fixer** or **Laravel Pint** for formatting.
+- Use **PHPStan** or **Psalm** for static analysis.
+- Keep Composer scripts checked in so the same commands run locally and in CI.
+
+## Imports
+
+- Add `use` statements for all referenced classes, interfaces, and traits.
+- Avoid relying on the global namespace unless the project explicitly prefers fully qualified names.
+
+## Error Handling
+
+- Throw exceptions for exceptional states; avoid returning `false`/`null` as hidden error channels in new code.
+- Convert framework/request input into validated DTOs before it reaches domain logic.
+
+## Reference
+
+See skill: `backend-patterns` for broader service/repository layering guidance.

package/.agent/rules/php/hooks.md

@@ -0,0 +1,24 @@
+---
+paths:
+  - "**/*.php"
+  - "**/composer.json"
+  - "**/phpstan.neon"
+  - "**/phpstan.neon.dist"
+  - "**/psalm.xml"
+---
+# PHP Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with PHP specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **Pint / PHP-CS-Fixer**: Auto-format edited `.php` files.
+- **PHPStan / Psalm**: Run static analysis after PHP edits in typed codebases.
+- **PHPUnit / Pest**: Run targeted tests for touched files or modules when edits affect behavior.
+
+## Warnings
+
+- Warn on `var_dump`, `dd`, `dump`, or `die()` left in edited files.
+- Warn when edited PHP files add raw SQL or disable CSRF/session protections.