moai-adk 0.32.8__py3-none-any.whl → 0.41.2__py3-none-any.whl

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

@@ -0,0 +1,291 @@
+# Java 21 LTS Reference Guide
+
+## Language Features Overview
+
+### Java 21 LTS (Long-Term Support)
+
+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
+
+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"]
+```
+
+### JVM Tuning for Containers
+
+```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
+```
+
+---
+
+## 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
+
+### Security
+- Never store passwords in plain text
+- Use BCrypt for password hashing
+- Validate all input data
+- Apply principle of least privilege
+
+---
+
+Last Updated: 2025-12-07
+Version: 1.0.0

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

@@ -0,0 +1,419 @@
+---
+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.1.0
+category: "language"
+modularized: false
+user-invocable: false
+updated: 2026-01-08
+status: "active"
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - mcp__context7__resolve-library-id
+  - mcp__context7__get-library-docs
+---
+
+## Quick Reference (30 seconds)
+
+JavaScript ES2024+ Development Specialist - Modern JavaScript with Node.js 22 LTS, multiple runtimes, and contemporary tooling.
+
+Auto-Triggers: `.js`, `.mjs`, `.cjs` files, `package.json`, Node.js projects, JavaScript discussions
+
+Core Stack:
+- 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/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
+
+Quick Commands:
+```bash
+# Create Vite project
+npm create vite@latest my-app -- --template vanilla
+
+# Initialize with modern tooling
+npm init -y && npm install -D vitest eslint @eslint/js
+
+# Run with Node.js watch mode
+node --watch server.js
+
+# Run TypeScript directly in Node.js 22+
+node --experimental-strip-types app.ts
+```
+
+---
+
+## Implementation Guide (5 minutes)
+
+### ES2024 Key Features
+
+Set Operations:
+```javascript
+const setA = new Set([1, 2, 3, 4]);
+const setB = new Set([3, 4, 5, 6]);
+
+setA.intersection(setB);      // Set {3, 4}
+setA.union(setB);             // Set {1, 2, 3, 4, 5, 6}
+setA.difference(setB);        // Set {1, 2}
+setA.symmetricDifference(setB); // Set {1, 2, 5, 6}
+setA.isSubsetOf(setB);        // false
+setA.isSupersetOf(setB);      // false
+setA.isDisjointFrom(setB);    // false
+```
+
+Promise.withResolvers():
+```javascript
+function createDeferred() {
+  const { promise, resolve, reject } = Promise.withResolvers();
+  return { promise, resolve, reject };
+}
+
+const deferred = createDeferred();
+setTimeout(() => deferred.resolve('done'), 1000);
+const result = await deferred.promise;
+```
+
+Immutable Array Methods:
+```javascript
+const original = [3, 1, 4, 1, 5];
+
+// New methods return new arrays (don't mutate)
+const sorted = original.toSorted();           // [1, 1, 3, 4, 5]
+const reversed = original.toReversed();       // [5, 1, 4, 1, 3]
+const spliced = original.toSpliced(1, 2, 9);  // [3, 9, 1, 5]
+const changed = original.with(2, 99);         // [3, 1, 99, 1, 5]
+
+console.log(original); // [3, 1, 4, 1, 5] - unchanged
+```
+
+Object.groupBy and Map.groupBy:
+```javascript
+const items = [
+  { type: 'fruit', name: 'apple' },
+  { type: 'vegetable', name: 'carrot' },
+  { type: 'fruit', name: 'banana' },
+];
+
+const grouped = Object.groupBy(items, item => item.type);
+// { fruit: [{...}, {...}], vegetable: [{...}] }
+
+const mapGrouped = Map.groupBy(items, item => item.type);
+// Map { 'fruit' => [...], 'vegetable' => [...] }
+```
+
+### ES2025 Features
+
+Import Attributes (JSON Modules):
+```javascript
+import config from './config.json' with { type: 'json' };
+import styles from './styles.css' with { type: 'css' };
+
+console.log(config.apiUrl);
+```
+
+RegExp.escape:
+```javascript
+const userInput = 'hello (world)';
+const safePattern = RegExp.escape(userInput);
+// "hello\\ \\(world\\)"
+const regex = new RegExp(safePattern);
+```
+
+### Node.js 22 LTS Features
+
+Built-in WebSocket Client:
+```javascript
+const ws = new WebSocket('wss://example.com/socket');
+
+ws.addEventListener('open', () => {
+  ws.send(JSON.stringify({ type: 'hello' }));
+});
+
+ws.addEventListener('message', (event) => {
+  const data = JSON.parse(event.data);
+  console.log('Received:', data);
+});
+```
+
+Native TypeScript Support (Experimental):
+```bash
+# Run .ts files directly in Node.js 22.6+
+node --experimental-strip-types app.ts
+
+# In Node.js 22.18+, type stripping is enabled by default
+node app.ts
+```
+
+Watch Mode (Stable):
+```bash
+# Auto-restart on file changes
+node --watch server.js
+
+# Watch specific files
+node --watch-path=./src --watch-path=./config server.js
+```
+
+Permission Model:
+```bash
+# Restrict file system access
+node --permission --allow-fs-read=/app/data server.js
+
+# Restrict network access
+node --permission --allow-net=api.example.com server.js
+```
+
+### Backend Frameworks
+
+Express (Traditional):
+```javascript
+import express from 'express';
+
+const app = express();
+app.use(express.json());
+
+app.get('/api/users', async (req, res) => {
+  const users = await db.users.findAll();
+  res.json(users);
+});
+
+app.post('/api/users', async (req, res) => {
+  const user = await db.users.create(req.body);
+  res.status(201).json(user);
+});
+
+app.listen(3000, () => console.log('Server running on port 3000'));
+```
+
+Fastify (High Performance):
+```javascript
+import Fastify from 'fastify';
+
+const fastify = Fastify({ logger: true });
+
+const userSchema = {
+  body: {
+    type: 'object',
+    required: ['name', 'email'],
+    properties: {
+      name: { type: 'string', minLength: 2 },
+      email: { type: 'string', format: 'email' },
+    },
+  },
+};
+
+fastify.post('/api/users', { schema: userSchema }, async (request, reply) => {
+  const user = await db.users.create(request.body);
+  return reply.code(201).send(user);
+});
+
+await fastify.listen({ port: 3000 });
+```
+
+Hono (Edge-First):
+```javascript
+import { Hono } from 'hono';
+import { cors } from 'hono/cors';
+import { logger } from 'hono/logger';
+import { validator } from 'hono/validator';
+
+const app = new Hono();
+
+app.use('*', logger());
+app.use('/api/*', cors());
+
+app.get('/api/users', async (c) => {
+  const users = await db.users.findAll();
+  return c.json(users);
+});
+
+app.post('/api/users',
+  validator('json', (value, c) => {
+    if (!value.name || !value.email) {
+      return c.json({ error: 'Invalid input' }, 400);
+    }
+    return value;
+  }),
+  async (c) => {
+    const user = await db.users.create(c.req.valid('json'));
+    return c.json(user, 201);
+  }
+);
+
+export default app;
+```
+
+### Testing with Vitest
+
+Configuration:
+```javascript
+// vitest.config.js
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+    },
+  },
+});
+```
+
+Test Example:
+```javascript
+// user.test.js
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createUser, getUser } from './user.js';
+
+describe('User Service', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should create a user', async () => {
+    const user = await createUser({ name: 'John', email: 'john@example.com' });
+    expect(user).toMatchObject({ name: 'John', email: 'john@example.com' });
+    expect(user.id).toBeDefined();
+  });
+
+  it('should throw on invalid email', async () => {
+    await expect(createUser({ name: 'John', email: 'invalid' }))
+      .rejects.toThrow('Invalid email');
+  });
+});
+```
+
+### ESLint 9 Flat Config
+
+```javascript
+// eslint.config.js
+import js from '@eslint/js';
+import globals from 'globals';
+
+export default [
+  js.configs.recommended,
+  {
+    languageOptions: {
+      ecmaVersion: 2025,
+      sourceType: 'module',
+      globals: {
+        ...globals.node,
+        ...globals.es2025,
+      },
+    },
+    rules: {
+      'no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+      'no-console': ['warn', { allow: ['warn', 'error'] }],
+      'prefer-const': 'error',
+      'no-var': 'error',
+    },
+  },
+];
+```
+
+### Biome (All-in-One)
+
+```json
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json",
+  "organizeImports": { "enabled": true },
+  "linter": {
+    "enabled": true,
+    "rules": { "recommended": true }
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "semicolons": "always"
+    }
+  }
+}
+```
+
+---
+
+## Advanced Patterns
+
+For comprehensive documentation including advanced async patterns, module system details, performance optimization, and production deployment configurations, see:
+
+- [reference.md](reference.md) - Complete API reference, Context7 library mappings, package manager comparison
+- [examples.md](examples.md) - Production-ready code examples, full-stack patterns, testing templates
+
+### Context7 Integration
+
+```javascript
+// Node.js - mcp__context7__get_library_docs("/nodejs/node", "esm modules async", 1)
+// Express - mcp__context7__get_library_docs("/expressjs/express", "middleware routing", 1)
+// Fastify - mcp__context7__get_library_docs("/fastify/fastify", "plugins hooks", 1)
+// Hono - mcp__context7__get_library_docs("/honojs/hono", "middleware validators", 1)
+// Vitest - mcp__context7__get_library_docs("/vitest-dev/vitest", "mocking coverage", 1)
+```
+
+---
+
+## Works Well With
+
+- `moai-lang-typescript` - TypeScript integration, type checking with JSDoc
+- `moai-domain-backend` - API design, microservices architecture
+- `moai-domain-database` - Database integration, ORM patterns
+- `moai-workflow-testing` - TDD workflows, testing strategies
+- `moai-foundation-quality` - Code quality standards
+- `moai-essentials-debug` - Debugging JavaScript applications
+
+---
+
+## Quick Troubleshooting
+
+Module System Issues:
+```bash
+# Check package.json type
+cat package.json | grep '"type"'
+
+# ESM: "type": "module" - use import/export
+# CommonJS: "type": "commonjs" or omitted - use require/module.exports
+```
+
+Node.js Version Check:
+```bash
+node --version  # Should be 20.x or 22.x LTS
+npm --version   # Should be 10.x+
+```
+
+Common Fixes:
+```bash
+# Clear npm cache
+npm cache clean --force
+
+# Delete node_modules and reinstall
+rm -rf node_modules package-lock.json && npm install
+
+# Fix permission issues
+npm config set prefix ~/.npm-global
+```
+
+ESM/CommonJS Interop:
+```javascript
+// Import CommonJS from ESM
+import pkg from 'commonjs-package';
+const { namedExport } = pkg;
+
+// Dynamic import in CommonJS
+const { default: esmModule } = await import('esm-package');
+```
+
+---
+
+Last Updated: 2026-01-05
+Status: Active (v1.1.0)