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

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

@@ -1,31 +1,291 @@
-# moai-lang-java - CLI Reference
+# Java 21 LTS Reference Guide
 
-_Last updated: 2025-10-22_
+## Language Features Overview
 
-## Quick Reference
+### Java 21 LTS (Long-Term Support)
 
-### Installation
+Version Information:
+- Latest: 21.0.5 (LTS, support until September 2031)
+- Key JEPs: 444 (Virtual Threads), 441 (Pattern Matching), 440 (Record Patterns)
+- JVM: HotSpot, GraalVM Native Image support
 
-```bash
-# Installation commands
+Core Features Summary:
+
+| Feature | Status | JEP | Description |
+|---------|--------|-----|-------------|
+| Virtual Threads | Final | 444 | Lightweight threads for high-concurrency |
+| Pattern Matching for switch | Final | 441 | Type patterns with guards |
+| Record Patterns | Final | 440 | Destructuring in pattern matching |
+| Sealed Classes | Final | 409 | Restrict class hierarchies |
+| Sequenced Collections | Final | 431 | Ordered collection interfaces |
+| String Templates | Preview | 430 | Embedded expressions in strings |
+| Structured Concurrency | Preview | 453 | Scope-based concurrency |
+| Scoped Values | Preview | 446 | Immutable inherited values |
+
+---
+
+## Enterprise Ecosystem
+
+### Spring Boot 3.3
+
+Key Features:
+- Native GraalVM compilation support
+- Virtual Threads integration
+- Observability with Micrometer
+- Problem Details for HTTP APIs (RFC 7807)
+- SSL Bundle support
+
+Configuration:
+```properties
+# application.properties
+spring.threads.virtual.enabled=true
+spring.datasource.url=jdbc:postgresql://localhost:5432/db
+spring.datasource.hikari.maximum-pool-size=10
+spring.jpa.hibernate.ddl-auto=validate
+spring.jpa.show-sql=false
+```
+
+### Spring Security 6
+
+Key Features:
+- Lambda DSL configuration
+- OAuth2 Resource Server
+- JWT token validation
+- Method security with annotations
+
+### Hibernate 7 / Jakarta Persistence
+
+Key Features:
+- Java 21 record support
+- Improved batch processing
+- StatelessSession for bulk operations
+- Native SQL result mapping
+
+---
+
+## Context7 Library Mappings
+
+### Spring Ecosystem
+```
+/spring-projects/spring-boot - Spring Boot framework
+/spring-projects/spring-framework - Spring Core framework
+/spring-projects/spring-security - Security framework
+/spring-projects/spring-data-jpa - JPA repositories
+/spring-projects/spring-data-r2dbc - Reactive database access
+```
+
+### Persistence
+```
+/hibernate/hibernate-orm - Hibernate ORM
+/querydsl/querydsl - Type-safe queries
+/flyway/flyway - Database migrations
+/liquibase/liquibase - Database change management
+```
+
+### Testing
+```
+/junit-team/junit5 - JUnit 5 testing
+/mockito/mockito - Mocking framework
+/testcontainers/testcontainers-java - Container testing
+/assertj/assertj - Fluent assertions
+```
+
+### Build Tools
+```
+/gradle/gradle - Build automation
+/apache/maven - Project management
+```
+
+### Utilities
+```
+/resilience4j/resilience4j - Fault tolerance
+/open-telemetry/opentelemetry-java - Observability
+/micrometer-metrics/micrometer - Application metrics
+/mapstruct/mapstruct - Object mapping
+```
+
+---
+
+## Performance Characteristics
+
+### JVM Startup and Memory
+
+| Runtime | Cold Start | Warm Start | Base Memory | With GraalVM Native |
+|---------|------------|------------|-------------|---------------------|
+| Java 21 (HotSpot) | 2-5s | <100ms | 256MB+ | 50-100ms, 64MB |
+| Spring Boot 3.3 | 3-6s | <100ms | 512MB+ | 100-200ms, 128MB |
+
+### Throughput Benchmarks
+
+| Framework | Requests/sec | Latency P99 | Memory Usage |
+|-----------|-------------|-------------|--------------|
+| Spring Boot 3.3 (Virtual Threads) | 150K | 2ms | 512MB |
+| Spring WebFlux | 180K | 1.5ms | 384MB |
+| Spring MVC (Thread Pool) | 80K | 5ms | 768MB |
+
+### Compilation Times
+
+| Build Tool | Clean Build | Incremental | With Cache |
+|------------|------------|-------------|------------|
+| Maven 3.9 | 30-60s | 5-10s | 15-30s |
+| Gradle 8.5 | 20-40s | 3-8s | 10-20s |
+
+---
+
+## Development Environment
+
+### IDE Support
+
+| IDE | Java Support | Spring Support | Best For |
+|-----|--------------|----------------|----------|
+| IntelliJ IDEA | Excellent | Excellent | Enterprise development |
+| VS Code | Good | Good | Lightweight editing |
+| Eclipse | Good | Good | Legacy projects |
+
+### Recommended IntelliJ Plugins
+- Spring Boot Assistant
+- JPA Buddy
+- TestContainers
+- Key Promoter X
+- Lombok
+
+### Linters and Formatters
+
+| Tool | Purpose | Config File |
+|------|---------|-------------|
+| Checkstyle | Code style | checkstyle.xml |
+| SpotBugs | Bug detection | spotbugs-exclude.xml |
+| PMD | Code analysis | ruleset.xml |
+| google-java-format | Formatting | N/A (convention) |
+
+---
+
+## Container Optimization
+
+### Docker Multi-Stage Build
+
+```dockerfile
+FROM eclipse-temurin:21-jdk-alpine AS builder
+WORKDIR /app
+COPY . .
+RUN ./gradlew bootJar --no-daemon
+
+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/build/libs/*.jar app.jar
+USER app
+EXPOSE 8080
+ENTRYPOINT ["java", "-jar", "app.jar"]
+```
+
+### GraalVM Native Image
+
+```dockerfile
+FROM ghcr.io/graalvm/native-image-community:21 AS builder
+WORKDIR /app
+COPY . .
+RUN ./gradlew nativeCompile
+
+FROM gcr.io/distroless/base-debian12
+COPY --from=builder /app/build/native/nativeCompile/app /app
+ENTRYPOINT ["/app"]
 ```
 
-### Common Commands
+### JVM Tuning for Containers
 
-```bash
-# Test
-# Lint
-# Format
-# Build
+```yaml
+# Kubernetes deployment
+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
 ```
 
-## Tool Versions (2025-10-22)
+---
+
+## Migration Guide: Java 17 to 21
+
+### Key Changes
+
+1. Virtual Threads:
+   - Replace `Executors.newFixedThreadPool()` with `Executors.newVirtualThreadPerTaskExecutor()`
+   - Consider structured concurrency for complex concurrent tasks
+
+2. Pattern Matching:
+   - Refactor `instanceof` checks to pattern matching
+   - Use guarded patterns with `when` clause
+
+3. Record Patterns:
+   - Use destructuring in switch expressions
+   - Combine with sealed classes for exhaustive matching
+
+4. Sequenced Collections:
+   - Use `SequencedCollection.getFirst()` and `getLast()`
+   - Replace iteration with sequence methods
+
+### Gradle Configuration Update
+
+```kotlin
+// Before (Java 17)
+java { toolchain { languageVersion = JavaLanguageVersion.of(17) } }
+
+// After (Java 21)
+java { toolchain { languageVersion = JavaLanguageVersion.of(21) } }
+```
+
+### Maven Configuration Update
+
+```xml
+<!-- Before -->
+<java.version>17</java.version>
+
+<!-- After -->
+<java.version>21</java.version>
+```
+
+---
+
+## Best Practices
+
+### Code Style
+- Use records for DTOs and value objects
+- Prefer sealed interfaces for type hierarchies
+- Use pattern matching in switch expressions
+- Apply virtual threads for I/O-bound operations
+
+### Spring Boot
+- Use constructor injection (no @Autowired on constructors)
+- Apply @Transactional at service layer
+- Use records for request/response DTOs
+- Configure proper connection pooling
+
+### Testing
+- Use JUnit 5 nested tests for organization
+- Apply @DisplayName for readable test names
+- Use TestContainers for integration tests
+- Mock external dependencies with Mockito
 
-- **Java**: 23.0.0
-- **JUnit**: 5.11.0
-- **Maven**: 3.9.9
-- **Gradle**: 8.12.0
+### Security
+- Never store passwords in plain text
+- Use BCrypt for password hashing
+- Validate all input data
+- Apply principle of least privilege
 
 ---
 
-_For detailed usage, see SKILL.md_
+Last Updated: 2025-12-07
+Version: 1.0.0

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

@@ -1,125 +1,179 @@
 ---
-name: moai-lang-javascript
-version: 2.0.0
-created: 2025-10-22
-updated: 2025-10-22
-status: active
-description: JavaScript ES2024+ best practices with Jest 29, ESLint 9, Prettier 3, and npm package management.
-keywords: ['javascript', 'testing', 'jest', 'eslint', 'prettier', 'nodejs']
+name: "moai-lang-javascript"
+description: "JavaScript ES2024+ development specialist covering Node.js 22 LTS, Bun 1.x (serve, SQLite, S3, shell, test), Deno 2.x, testing (Vitest, Jest), linting (ESLint 9, Biome), and backend frameworks (Express, Fastify, Hono). Use when developing JavaScript APIs, web applications, or Node.js projects."
+version: 1.2.0
+category: "language"
+modularized: false
+user-invocable: false
+tags:
+  [
+    "language",
+    "javascript",
+    "nodejs",
+    "bun",
+    "deno",
+    "vitest",
+    "eslint",
+    "express",
+  ]
+updated: 2026-01-11
+status: "active"
 allowed-tools:
   - Read
+  - Grep
+  - Glob
   - Bash
+  - mcp__context7__resolve-library-id
+  - mcp__context7__get-library-docs
 ---
 
-# Lang Javascript Skill
+## Quick Reference (30 seconds)
 
-## Skill Metadata
+JavaScript ES2024+ Development Specialist - Modern JavaScript with Node.js 22 LTS, multiple runtimes, and contemporary tooling.
 
-| Field | Value |
-| ----- | ----- |
-| **Skill Name** | moai-lang-javascript |
-| **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: Files with .js, .mjs, or .cjs extensions, package.json, Node.js projects, JavaScript discussions
 
----
+Core Stack:
 
-## What It Does
+- ES2024+: Set methods, Promise.withResolvers, immutable arrays, import attributes
+- Node.js 22 LTS: Native TypeScript, built-in WebSocket, stable watch mode
+- Runtimes: Node.js 20 and 22 LTS, Deno 2.x, Bun 1.x
+- Testing: Vitest, Jest, Node.js test runner
+- Linting: ESLint 9 flat config, Biome
+- Bundlers: Vite, esbuild, Rollup
+- Frameworks: Express, Fastify, Hono, Koa
 
-JavaScript ES2024+ best practices with Jest 29, ESLint 9, Prettier 3, and npm package management.
+Quick Commands:
 
-**Key capabilities**:
-- ✅ Best practices enforcement for language domain
-- ✅ TRUST 5 principles integration
-- ✅ Latest tool versions (2025-10-22)
-- ✅ TDD workflow support
+Create a Vite project using npm create vite with latest tag, project name, and vanilla template. Initialize with modern tooling using npm init and npm install with D flag for vitest, eslint, and eslint/js. Run with Node.js watch mode using node with watch flag. Run TypeScript directly in Node.js 22+ using node with experimental-strip-types flag.
 
 ---
 
-## When to Use
+## Implementation Guide (5 minutes)
 
-**Automatic triggers**:
-- Related code discussions and file patterns
-- SPEC implementation (`/alfred:2-run`)
-- Code review requests
+### ES2024 Key Features
 
-**Manual invocation**:
-- Review code for TRUST 5 compliance
-- Design new features
-- Troubleshoot issues
+Set Operations:
 
----
+Create setA with values 1, 2, 3, 4 and setB with values 3, 4, 5, 6. Call setA.intersection with setB to get Set containing 3 and 4. Call setA.union with setB to get Set containing 1 through 6. Call setA.difference with setB to get Set containing 1 and 2. Call setA.symmetricDifference with setB to get Set containing 1, 2, 5, and 6. Call isSubsetOf, isSupersetOf, and isDisjointFrom methods for set comparisons.
 
-## Tool Version Matrix (2025-10-22)
+Promise.withResolvers:
 
-| Tool | Version | Purpose | Status |
-|------|---------|---------|--------|
-| **Node.js** | 22.11.0 | Primary | ✅ Current |
-| **Jest** | 29.7.0 | Primary | ✅ Current |
-| **ESLint** | 9.16.0 | Primary | ✅ Current |
-| **Prettier** | 3.4.1 | Primary | ✅ Current |
-| **npm** | 10.9.0 | Primary | ✅ Current |
+Create a createDeferred function that destructures promise, resolve, and reject from Promise.withResolvers call. Return an object with these three properties. Create a deferred instance, set a timeout to resolve with done after 1000 milliseconds, and await the promise for the result.
 
----
+Immutable Array Methods:
 
-## Inputs
+Create original array with values 3, 1, 4, 1, 5. Call toSorted to get new sorted array without mutating original. Call toReversed to get new reversed array. Call toSpliced with index 1, delete count 2, and insert value 9. Call with method at index 2 with value 99 to get new array with replaced element. The original array remains unchanged.
 
-- Language-specific source directories
-- Configuration files
-- Test suites and sample data
+Object.groupBy and Map.groupBy:
 
-## Outputs
+Create items array with objects containing type and name properties. Call Object.groupBy with items and a function that returns item.type to get an object with arrays grouped by type. Call Map.groupBy with the same arguments to get a Map with type keys and array values.
 
-- Test/lint execution plan
-- TRUST 5 review checkpoints
-- Migration guidance
+### ES2025 Features
 
-## Failure Modes
+Import Attributes for JSON Modules:
 
-- When required tools are not installed
-- When dependencies are missing
-- When test coverage falls below 85%
+Import config from config.json with type attribute set to json. Import styles from styles.css with type attribute set to css. Access config.apiUrl property.
 
-## Dependencies
+RegExp.escape:
 
-- Access to project files via Read/Bash tools
-- Integration with `moai-foundation-langs` for language detection
-- Integration with `moai-foundation-trust` for quality gates
+Create userInput string with special characters like parentheses. Call RegExp.escape with userInput to get escaped pattern string. Create new RegExp with the safe pattern.
 
----
+### Node.js 22 LTS Features
+
+Built-in WebSocket Client:
+
+Create new WebSocket with wss URL. Add event listener for open event that sends JSON stringified message. Add event listener for message event that parses event.data as JSON and logs the received data.
+
+Native TypeScript Support Experimental:
+
+Run .ts files directly in Node.js 22.6+ using node with experimental-strip-types flag. In Node.js 22.18+, type stripping is enabled by default so files can be run directly.
+
+Watch Mode Stable:
+
+Use node with watch flag for auto-restart on file changes. Use watch-path flag multiple times to watch specific directories like src and config.
+
+Permission Model:
+
+Use node with permission flag and allow-fs-read set to a specific path to restrict file system access. Use allow-net flag with domain name to restrict network access.
+
+### Backend Frameworks
+
+Express Traditional Pattern:
+
+Import express. Create app by calling express function. Use express.json middleware. Create a get endpoint at api/users that awaits database query and responds with json. Create a post endpoint that creates a user and responds with status 201 and json. Call listen on port 3000 with callback logging server running.
+
+Fastify High Performance Pattern:
+
+Import Fastify. Create fastify instance with logger set to true. Define userSchema with body containing type object, required array with name and email, and properties with validation constraints. Create a post endpoint with schema option and async handler that creates user and returns with code 201. Call listen with port 3000.
+
+Hono Edge-First Pattern:
+
+Import Hono and middleware functions. Create app instance. Use logger middleware for all routes. Use cors middleware for api routes. Create get endpoint at api/users that awaits database query and returns c.json. Create post endpoint with validator middleware that checks for required fields, then creates user and returns c.json with status 201. Export app as default.
 
-## References (Latest Documentation)
+### Testing with Vitest
 
-_Documentation links updated 2025-10-22_
+Configuration:
+
+Create vitest.config.js with defineConfig. Set test object with globals true, environment node, and coverage with provider v8 and reporters for text, json, and html.
+
+Test Example:
+
+In test file, import describe, it, expect, vi, and beforeEach from vitest. Import functions to test. Create describe block for User Service. In beforeEach, call vi.clearAllMocks. Create it block for should create a user that awaits createUser and expects result to match object with name and email, and id to be defined. Create it block for should throw on invalid email that expects createUser to reject with Invalid email error.
+
+### ESLint 9 Flat Config
+
+Create eslint.config.js. Import js from eslint/js and globals. Export array with js.configs.recommended followed by object with languageOptions containing ecmaVersion 2025, sourceType module, and globals merged from globals.node and globals.es2025. Set rules for no-unused-vars with error and args ignore pattern, no-console with warn and allowed methods, prefer-const as error, and no-var as error.
+
+### Biome All-in-One
+
+Create biome.json with schema URL. Enable organizeImports. Set linter enabled with recommended rules. Set formatter enabled with indentStyle space and indentWidth 2. Under javascript.formatter, set quoteStyle to single and semicolons to always.
 
 ---
 
-## Changelog
+## Advanced Patterns
+
+For comprehensive documentation including advanced async patterns, module system details, performance optimization, and production deployment configurations, see:
+
+- reference.md for complete API reference, Context7 library mappings, and package manager comparison
+- examples.md for production-ready code examples, full-stack patterns, and testing templates
+
+### Context7 Integration
 
-- **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
+For Node.js documentation, use context7 get library docs with nodejs/node and topics like esm modules async. For Express, use expressjs/express with middleware routing. For Fastify, use fastify/fastify with plugins hooks. For Hono, use honojs/hono with middleware validators. For Vitest, use vitest-dev/vitest with mocking coverage.
 
 ---
 
 ## Works Well With
 
-- `moai-foundation-trust` (quality gates)
-- `moai-alfred-code-reviewer` (code review)
-- `moai-essentials-debug` (debugging support)
+- moai-lang-typescript for TypeScript integration and type checking with JSDoc
+- moai-domain-backend for API design and microservices architecture
+- moai-domain-database for database integration and ORM patterns
+- moai-workflow-testing for TDD workflows and testing strategies
+- moai-foundation-quality for code quality standards
+- moai-essentials-debug for debugging JavaScript applications
 
 ---
 
-## Best Practices
+## Quick Troubleshooting
 
-✅ **DO**:
-- Follow language best practices
-- Use latest stable tool versions
-- Maintain test coverage ≥85%
-- Document all public APIs
+Module System Issues:
+
+Check package.json for type field. ESM uses type module with import and export. CommonJS uses type commonjs or omits the field and uses require and module.exports.
+
+Node.js Version Check:
+
+Run node with version flag for 20.x or 22.x LTS. Run npm with version flag for 10.x or later.
+
+Common Fixes:
+
+Clear npm cache with npm cache clean using force flag. Delete node_modules and package-lock.json then run npm install. Fix permission issues by setting npm config prefix to home directory npm-global folder.
+
+ESM and CommonJS Interop:
+
+To import CommonJS from ESM, import the default then destructure named exports from it. For dynamic import in CommonJS, use await import and destructure the default property.
+
+---
 
-❌ **DON'T**:
-- Skip quality gates
-- Use deprecated tools
-- Ignore security warnings
-- Mix testing frameworks
+Last Updated: 2026-01-11
+Status: Active (v1.2.0)