moai-adk 0.8.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-lang-scala/reference.md

@@ -1,30 +1,423 @@
-# moai-lang-scala - CLI Reference
+# Scala 3.4+ Reference Guide
 
-_Last updated: 2025-10-22_
+## Complete Language Coverage
 
-## Quick Reference
+### Scala 3.4 (November 2025)
 
-### Installation
+Version Information:
+- Latest: 3.4.2
+- Dotty: New compiler with improved type system
+- TASTy: Portable intermediate representation
+- JVM Target: 11, 17, 21 (recommended: 21)
+
+Core Features:
+
+- Export Clauses: Selective member export from composed objects
+- Extension Methods: Type-safe extensions without implicit classes
+- Enum Types: Algebraic data types with exhaustive pattern matching
+- Opaque Types: Zero-cost type abstractions
+- Union Types: A or B type unions for flexible APIs
+- Intersection Types: A and B type combinations
+- Match Types: Type-level computation and pattern matching
+- Inline Methods: Compile-time evaluation and metaprogramming
+- Given/Using: Context parameters replacing implicits
+- Braceless Syntax: Optional significant indentation
+
+---
+
+## Context7 Library Mappings
+
+### Core Scala
+
+```
+/scala/scala3 - Scala 3.4 language reference
+/scala/scala-library - Standard library
+```
+
+### Effect Systems
+
+```
+/typelevel/cats-effect - Cats Effect 3.5 (Pure FP runtime)
+/typelevel/cats - Cats 2.10 (Functional abstractions)
+/zio/zio - ZIO 2.1 (Effect system)
+/zio/zio-streams - ZIO Streams (Streaming)
+```
+
+### Akka Ecosystem
+
+```
+/akka/akka - Akka 2.9 (Typed actors, streams)
+/akka/akka-http - Akka HTTP (REST APIs)
+/akka/alpakka - Akka Alpakka (Connectors)
+```
+
+### HTTP and Web
+
+```
+/http4s/http4s - Http4s 0.24 (Functional HTTP)
+/softwaremill/tapir - Tapir 1.10 (API-first design)
+```
+
+### JSON
+
+```
+/circe/circe - Circe 0.15 (JSON parsing)
+/zio/zio-json - ZIO JSON 0.6 (Fast JSON)
+```
+
+### Database
+
+```
+/tpolecat/doobie - Doobie 1.0 (Functional JDBC)
+/slick/slick - Slick 3.5 (FRM)
+/getquill/quill - Quill 4.8 (Compile-time SQL)
+```
+
+### Big Data
 
-```bash
-# Installation commands
+```
+/apache/spark - Apache Spark 3.5
+/apache/flink - Apache Flink 1.19
+/apache/kafka - Kafka Clients 3.7
 ```
 
-### Common Commands
+### Testing
 
-```bash
-# Test
-# Lint
-# Format
-# Build
 ```
+/scalatest/scalatest - ScalaTest 3.2
+/typelevel/munit-cats-effect - MUnit Cats Effect 2.0
+/zio/zio-test - ZIO Test 2.1
+```
+
+---
+
+## Testing Patterns
+
+### ScalaTest with Akka TestKit
+
+```scala
+class UserActorSpec extends ScalaTestWithActorTestKit with AnyWordSpecLike with Matchers:
+  import UserActor.*
+
+  val mockRepository: UserRepository = mock[UserRepository]
+
+  "UserActor" should {
+    "return user when found" in {
+      val testUser = User(1L, "John", "john@example.com")
+      when(mockRepository.findById(1L)).thenReturn(Some(testUser))
+
+      val actor = spawn(UserActor(mockRepository))
+      val probe = createTestProbe[Option[User]]()
+
+      actor ! GetUser(1L, probe.ref)
+
+      probe.expectMessage(Some(testUser))
+      verify(mockRepository).findById(1L)
+    }
+
+    "return None when user not found" in {
+      when(mockRepository.findById(999L)).thenReturn(None)
+
+      val actor = spawn(UserActor(mockRepository))
+      val probe = createTestProbe[Option[User]]()
+
+      actor ! GetUser(999L, probe.ref)
+
+      probe.expectMessage(None)
+    }
+
+    "handle multiple requests concurrently" in {
+      val users = (1 to 100).map(i => User(i.toLong, s"User$i", s"user$i@example.com"))
+      users.foreach(u => when(mockRepository.findById(u.id)).thenReturn(Some(u)))
+
+      val actor = spawn(UserActor(mockRepository))
+      val probes = users.map(_ => createTestProbe[Option[User]]())
+
+      users.zip(probes).foreach { case (user, probe) =>
+        actor ! GetUser(user.id, probe.ref)
+      }
+
+      users.zip(probes).foreach { case (user, probe) =>
+        probe.expectMessage(Some(user))
+      }
+    }
+  }
+```
+
+### Cats Effect Testing (MUnit)
+
+```scala
+class UserServiceSpec extends CatsEffectSuite:
+  val mockRepository = mock[UserRepository[IO]]
+
+  test("should fetch user successfully") {
+    val testUser = User(1L, "John", "john@example.com")
+    when(mockRepository.findById(1L)).thenReturn(IO.pure(Some(testUser)))
+
+    val service = UserService(mockRepository)
+
+    service.findById(1L).map { result =>
+      assertEquals(result, Some(testUser))
+    }
+  }
+
+  test("should handle concurrent operations") {
+    val users = (1 to 10).map(i => User(i.toLong, s"User$i", s"user$i@example.com")).toList
+    users.foreach(u => when(mockRepository.findById(u.id)).thenReturn(IO.pure(Some(u))))
+
+    val service = UserService(mockRepository)
+
+    val results = users.parTraverse(u => service.findById(u.id))
+
+    results.map { list =>
+      assertEquals(list.flatten.size, 10)
+    }
+  }
+
+  test("should timeout slow operations") {
+    when(mockRepository.findById(any[Long])).thenReturn(IO.sleep(5.seconds) *> IO.none)
+
+    val service = UserService(mockRepository)
+
+    service.findById(1L)
+      .timeout(100.millis)
+      .attempt
+      .map { result =>
+        assert(result.isLeft)
+        assert(result.left.exists(_.isInstanceOf[TimeoutException]))
+      }
+  }
+```
+
+### ZIO Testing
+
+```scala
+object UserServiceSpec extends ZIOSpecDefault:
+  val testUser = User(1L, "John", "john@example.com")
+
+  val mockRepositoryLayer: ULayer[UserRepository] = ZLayer.succeed {
+    new UserRepository:
+      def findById(id: Long): UIO[Option[User]] =
+        if id == 1L then ZIO.some(testUser) else ZIO.none
+      def save(user: User): UIO[User] = ZIO.succeed(user)
+  }
+
+  def spec = suite("UserService")(
+    test("should find existing user") {
+      for
+        service <- ZIO.service[UserService]
+        result <- service.findById(1L)
+      yield assertTrue(result == Some(testUser))
+    }.provide(mockRepositoryLayer, UserService.layer),
+
+    test("should return None for non-existent user") {
+      for
+        service <- ZIO.service[UserService]
+        result <- service.findById(999L)
+      yield assertTrue(result.isEmpty)
+    }.provide(mockRepositoryLayer, UserService.layer),
+
+    test("should handle parallel requests") {
+      for
+        service <- ZIO.service[UserService]
+        results <- ZIO.foreachPar(1 to 100)(id => service.findById(id.toLong))
+      yield assertTrue(results.flatten.size == 1)
+    }.provide(mockRepositoryLayer, UserService.layer)
+  )
+```
+
+### Property-Based Testing (ScalaCheck)
+
+```scala
+class UserValidationSpec extends AnyFlatSpec with Matchers with ScalaCheckPropertyChecks:
+  "Email validation" should "accept valid emails" in {
+    forAll(Gen.alphaNumStr, Gen.alphaNumStr) { (local, domain) =>
+      whenever(local.nonEmpty && domain.nonEmpty) {
+        val email = s"$local@$domain.com"
+        Email(email) shouldBe a[Right[_, _]]
+      }
+    }
+  }
+
+  "UserId" should "roundtrip through string conversion" in {
+    forAll(Gen.posNum[Long]) { id =>
+      UserId.fromString(UserId(id).asString) shouldBe Some(UserId(id))
+    }
+  }
+```
+
+---
+
+## Performance Characteristics
+
+### JVM Startup and Memory
+
+- Cold Start: 3-6s (JVM warmup)
+- Warm Start: Less than 100ms
+- Base Memory: 512MB or more
+- GraalVM Native: Not recommended for Scala 3
+
+### Compilation Times
+
+- Clean Build: 60-120s
+- Incremental: 10-30s
+- With Cache: 30-60s
+- Note: Scala 3 compiler is faster than Scala 2
+
+### Framework Throughput
+
+- Http4s (Blaze): 160K requests per second, P99 latency 1.5ms
+- Http4s (Ember): 140K requests per second, P99 latency 2ms
+- Akka HTTP: 180K requests per second, P99 latency 1.2ms
+- ZIO HTTP: 170K requests per second, P99 latency 1.3ms
+
+---
+
+## Development Environment
+
+### IDE Support
+
+- IntelliJ IDEA: Good (Scala plugin required)
+- VS Code: Good (Metals extension)
+- Neovim: Good (Metals LSP)
+
+### Recommended Plugins
+
+IntelliJ IDEA:
+- Scala (by JetBrains)
+- ZIO for IntelliJ
+- Cats Support
+
+VS Code:
+- Scala (Metals)
+- Scala Syntax (official)
+
+### Linters and Formatters
+
+- Scalafmt: Code formatter (.scalafmt.conf)
+- Scalafix: Linting and refactoring
+- WartRemover: Code quality checks
+
+Example .scalafmt.conf:
+```hocon
+version = 3.7.17
+runner.dialect = scala3
+maxColumn = 100
+indent.main = 2
+indent.callSite = 2
+align.preset = more
+rewrite.rules = [SortImports, RedundantBraces, PreferCurlyFors]
+```
+
+---
+
+## Container Optimization
+
+### Docker Multi-Stage Build
+
+```dockerfile
+FROM eclipse-temurin:21-jdk-alpine AS builder
+WORKDIR /app
+COPY . .
+RUN sbt assembly
+
+FROM eclipse-temurin:21-jre-alpine
+RUN addgroup -g 1000 app && adduser -u 1000 -G app -s /bin/sh -D app
+WORKDIR /app
+COPY --from=builder /app/target/scala-3.4.2/*.jar app.jar
+USER app
+EXPOSE 8080
+ENTRYPOINT ["java", "-jar", "app.jar"]
+```
+
+### JVM Tuning for Containers
+
+```yaml
+containers:
+  - name: app
+    image: myapp:latest
+    resources:
+      requests:
+        memory: "512Mi"
+        cpu: "500m"
+      limits:
+        memory: "1Gi"
+        cpu: "1000m"
+    env:
+      - name: JAVA_OPTS
+        value: >-
+          -XX:+UseContainerSupport
+          -XX:MaxRAMPercentage=75.0
+          -XX:+UseG1GC
+          -XX:+UseStringDeduplication
+```
+
+---
+
+## Migration Guide: Scala 2.13 to 3.4
+
+Key Changes:
+
+1. Braceless Syntax: Optional significant indentation
+2. Given/Using: Replace `implicit` with `given` and `using`
+3. Extension Methods: Replace implicit classes with `extension`
+4. Enums: Replace sealed traits with `enum`
+5. Export Clauses: Replace trait mixing with exports
+6. Opaque Types: Replace value classes with opaque types
+7. Union Types: Replace Either with union types where appropriate
+8. Match Types: Replace type-level programming patterns
+
+Example Migration:
+
+Scala 2.13:
+```scala
+implicit class StringOps(s: String) {
+  def words: List[String] = s.split("\\s+").toList
+}
+
+implicit def jsonEncoder: JsonEncoder[String] = ???
+```
+
+Scala 3.4:
+```scala
+extension (s: String)
+  def words: List[String] = s.split("\\s+").toList
+
+given JsonEncoder[String] = ???
+```
+
+---
+
+## Effect System Comparison
+
+### Cats Effect vs ZIO
+
+Cats Effect:
+- Pure FP approach, minimal runtime
+- Better interop with Typelevel ecosystem
+- Smaller learning curve from cats-core
+- Resource safety via Resource type
+
+ZIO:
+- Rich built-in functionality (layers, config, logging)
+- Better error handling with typed errors
+- Comprehensive testing utilities
+- Larger standard library
+
+### When to Use Which
 
-## Tool Versions (2025-10-22)
+Use Cats Effect When:
+- Already using Typelevel libraries (http4s, doobie, fs2)
+- Prefer minimal runtime overhead
+- Team familiar with tagless final pattern
 
-- **Scala**: 3.6.0
-- **ScalaTest**: 3.2.19
-- **sbt**: 1.10.0
+Use ZIO When:
+- Building complex applications with many dependencies
+- Need comprehensive error handling
+- Prefer opinionated framework with batteries included
+- Building applications from scratch
 
 ---
 
-_For detailed usage, see SKILL.md_
+Last Updated: 2025-12-07
+Version: 1.0.0

moai_adk/templates/.claude/skills/moai-lang-swift/SKILL.md

@@ -1,123 +1,128 @@
 ---
-name: moai-lang-swift
-version: 2.0.0
-created: 2025-10-22
-updated: 2025-10-22
-status: active
-description: Swift 6+ best practices with XCTest, SwiftLint, and iOS/macOS development patterns.
-keywords: ['swift', 'xctest', 'swiftlint', 'ios', 'macos']
+name: "moai-lang-swift"
+description: "Swift 6+ development specialist covering SwiftUI, Combine, Swift Concurrency, and iOS patterns. Use when building iOS apps, macOS apps, or Apple platform applications."
+version: 2.1.0
+category: "language"
+modularized: true
+user-invocable: false
+tags: ['swift', 'swiftui', 'ios', 'macos', 'combine', 'concurrency']
 allowed-tools:
   - Read
-  - Bash
+  - Grep
+  - Glob
+  - mcp__context7__resolve-library-id
+  - mcp__context7__get-library-docs
+context7-libraries: ['/apple/swift', '/apple/swift-evolution']
+related-skills: ['moai-lang-kotlin', 'moai-lang-flutter']
+updated: 2026-01-11
+status: "active"
 ---
 
-# Lang Swift Skill
+# Swift 6+ Development Specialist
 
-## Skill Metadata
+Swift 6.0+ development expert for iOS/macOS with SwiftUI, Combine, and Swift Concurrency.
 
-| Field | Value |
-| ----- | ----- |
-| **Skill Name** | moai-lang-swift |
-| **Version** | 2.0.0 (2025-10-22) |
-| **Allowed tools** | Read (read_file), Bash (terminal) |
-| **Auto-load** | On demand when keywords detected |
-| **Tier** | Language |
+Auto-Triggers: Swift files (`.swift`), iOS/macOS projects, Xcode workspaces
 
----
+## Quick Reference
 
-## What It Does
+### Core Capabilities
 
-Swift 6+ best practices with XCTest, SwiftLint, and iOS/macOS development patterns.
+- Swift 6.0: Typed throws, complete concurrency, data-race safety by default
+- SwiftUI 6: @Observable macro, NavigationStack, modern declarative UI
+- Combine: Reactive programming with publishers and subscribers
+- Swift Concurrency: async/await, actors, TaskGroup, isolation
+- XCTest: Unit testing, UI testing, async test support
+- Swift Package Manager: Dependency management
 
-**Key capabilities**:
-- ✅ Best practices enforcement for language domain
-- ✅ TRUST 5 principles integration
-- ✅ Latest tool versions (2025-10-22)
-- ✅ TDD workflow support
+### Version Requirements
 
----
+- Swift: 6.0+
+- Xcode: 16.0+
+- iOS: 17.0+ (recommended), minimum 15.0
+- macOS: 14.0+ (recommended)
 
-## When to Use
+### Project Setup
 
-**Automatic triggers**:
-- Related code discussions and file patterns
-- SPEC implementation (`/alfred:2-run`)
-- Code review requests
+Package.swift Configuration: Begin with swift-tools-version comment set to 6.0. Import PackageDescription. Define let package with Package initializer. Set name, platforms array with .iOS and .macOS minimum versions, products array with library definitions, dependencies array with package URLs and version requirements, and targets array with target and testTarget entries including dependencies.
 
-**Manual invocation**:
-- Review code for TRUST 5 compliance
-- Design new features
-- Troubleshoot issues
+### Essential Patterns
 
----
+Basic @Observable ViewModel: Import Observation framework. Apply @Observable and @MainActor attributes to final class. Declare private(set) var properties for state. Create async functions that set isLoading true, use defer to set false, and assign fetched data with try? await and nil coalescing.
 
-## Tool Version Matrix (2025-10-22)
+Basic SwiftUI View: Define struct conforming to View. Declare @State private var for viewModel. In body computed property, use NavigationStack containing List iterating over viewModel items. Add .task modifier calling await on viewModel.load and .refreshable modifier for pull-to-refresh.
 
-| Tool | Version | Purpose | Status |
-|------|---------|---------|--------|
-| **Swift** | 6.0.0 | Primary | ✅ Current |
-| **XCTest** | 6.0.0 | Primary | ✅ Current |
-| **SwiftLint** | 0.57.0 | Primary | ✅ Current |
+Basic Actor for Thread Safety: Define actor type with private dictionary for cache. Create get function returning optional Data for key lookup. Create set function taking key and data parameters for cache storage.
 
----
+## Module Index
 
-## Inputs
+### Swift 6 Features
 
-- Language-specific source directories
-- Configuration files
-- Test suites and sample data
+[modules/swift6-features.md](modules/swift6-features.md)
 
-## Outputs
+- Typed throws for precise error handling
+- Complete concurrency checking
+- Data-race safety by default
+- Sendable conformance requirements
 
-- Test/lint execution plan
-- TRUST 5 review checkpoints
-- Migration guidance
+### SwiftUI Patterns
 
-## Failure Modes
+[modules/swiftui-patterns.md](modules/swiftui-patterns.md)
 
-- When required tools are not installed
-- When dependencies are missing
-- When test coverage falls below 85%
+- @Observable macro and state management
+- NavigationStack and navigation patterns
+- View lifecycle and .task modifier
+- Environment and dependency injection
 
-## Dependencies
+### Swift Concurrency
 
-- Access to project files via Read/Bash tools
-- Integration with `moai-foundation-langs` for language detection
-- Integration with `moai-foundation-trust` for quality gates
+[modules/concurrency.md](modules/concurrency.md)
 
----
+- async/await fundamentals
+- Actor isolation and @MainActor
+- TaskGroup for parallel execution
+- Custom executors and structured concurrency
 
-## References (Latest Documentation)
+### Combine Framework
 
-_Documentation links updated 2025-10-22_
+[modules/combine-reactive.md](modules/combine-reactive.md)
 
----
+- Publishers and Subscribers
+- Operators and transformations
+- async/await bridge patterns
+- Integration with SwiftUI
 
-## Changelog
+## Context7 Library Mappings
 
-- **v2.0.0** (2025-10-22): Major update with latest tool versions, comprehensive best practices, TRUST 5 integration
-- **v1.0.0** (2025-03-29): Initial Skill release
+### Core Swift
 
----
+- `/apple/swift` - Swift language and standard library
+- `/apple/swift-evolution` - Swift evolution proposals
+- `/apple/swift-package-manager` - SwiftPM documentation
+- `/apple/swift-async-algorithms` - Async sequence algorithms
 
-## Works Well With
+### Popular Libraries
 
-- `moai-foundation-trust` (quality gates)
-- `moai-alfred-code-reviewer` (code review)
-- `moai-essentials-debug` (debugging support)
+- `/Alamofire/Alamofire` - HTTP networking
+- `/onevcat/Kingfisher` - Image downloading and caching
+- `/realm/realm-swift` - Mobile database
+- `/pointfreeco/swift-composable-architecture` - TCA architecture
+- `/Quick/Quick` - BDD testing framework
+- `/Quick/Nimble` - Matcher framework
 
----
+## Testing Quick Start
+
+Async Test with MainActor: Apply @MainActor attribute to test class extending XCTestCase. Define test function with async throws. Create mock API and set mock data. Initialize system under test with mock. Call await on async method. Use XCTAssertEqual for count verification and XCTAssertFalse for boolean state checks.
+
+## Works Well With
 
-## Best Practices
+- `moai-lang-kotlin` - Android counterpart for cross-platform projects
+- `moai-lang-flutter` - Flutter/Dart for cross-platform mobile
+- `moai-domain-backend` - API integration and backend communication
+- `moai-foundation-quality` - iOS security best practices
+- `moai-workflow-testing` - Xcode debugging and profiling
 
-✅ **DO**:
-- Follow language best practices
-- Use latest stable tool versions
-- Maintain test coverage ≥85%
-- Document all public APIs
+## Resources
 
-❌ **DON'T**:
-- Skip quality gates
-- Use deprecated tools
-- Ignore security warnings
-- Mix testing frameworks
+- [reference.md](reference.md) - Architecture patterns, network layer, SwiftData
+- [examples.md](examples.md) - Production-ready code examples