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

moai_adk/templates/.claude/skills/moai-platform-vercel/reference.md

@@ -0,0 +1,360 @@
+# Vercel Platform Reference
+
+## Vercel CLI Commands
+
+### Project Management
+
+```bash
+# Initialize project
+vercel init
+
+# Link to existing project
+vercel link
+
+# Deploy to preview
+vercel
+
+# Deploy to production
+vercel --prod
+
+# List deployments
+vercel ls
+
+# Inspect deployment
+vercel inspect <deployment-url>
+
+# Rollback to previous deployment
+vercel rollback
+```
+
+### Environment Variables
+
+```bash
+# Add environment variable
+vercel env add <name> <environment>
+# Environments: production, preview, development
+
+# List environment variables
+vercel env ls
+
+# Remove environment variable
+vercel env rm <name> <environment>
+
+# Pull environment variables to local
+vercel env pull .env.local
+```
+
+### Domains
+
+```bash
+# Add custom domain
+vercel domains add <domain>
+
+# List domains
+vercel domains ls
+
+# Remove domain
+vercel domains rm <domain>
+
+# Inspect domain
+vercel domains inspect <domain>
+```
+
+### DNS Management
+
+```bash
+# List DNS records
+vercel dns ls <domain>
+
+# Add DNS record
+vercel dns add <domain> <subdomain> <type> <value>
+
+# Remove DNS record
+vercel dns rm <record-id>
+```
+
+### Storage
+
+```bash
+# Create storage
+vercel storage create <type> <name>
+# Types: kv, blob, postgres
+
+# List storage
+vercel storage ls
+
+# Remove storage
+vercel storage rm <name>
+```
+
+### Secrets (Legacy)
+
+```bash
+# Add secret
+vercel secrets add <name> <value>
+
+# List secrets
+vercel secrets ls
+
+# Remove secret
+vercel secrets rm <name>
+```
+
+## vercel.json Schema
+
+### Build Configuration
+
+```json
+{
+  "framework": "nextjs",
+  "buildCommand": "npm run build",
+  "installCommand": "npm install",
+  "outputDirectory": ".next",
+  "devCommand": "npm run dev"
+}
+```
+
+### Regions
+
+Available regions for functions:
+- `iad1` - Washington, D.C. (default)
+- `sfo1` - San Francisco
+- `fra1` - Frankfurt
+- `hnd1` - Tokyo
+- `syd1` - Sydney
+- `gru1` - Sao Paulo
+- `cle1` - Cleveland
+- `pdx1` - Portland
+- `dub1` - Dublin
+- `arn1` - Stockholm
+- `sin1` - Singapore
+- `bom1` - Mumbai
+- `cdg1` - Paris
+- `lhr1` - London
+
+### Function Configuration
+
+```json
+{
+  "functions": {
+    "api/**/*.ts": {
+      "memory": 1024,
+      "maxDuration": 30,
+      "runtime": "nodejs20.x"
+    }
+  }
+}
+```
+
+Memory options: 128, 256, 512, 1024, 2048, 3008 MB
+
+Duration limits by plan:
+- Hobby: 10 seconds
+- Pro: 60 seconds
+- Enterprise: 900 seconds
+
+### Cron Expression Syntax
+
+```
+*    *    *    *    *
+|    |    |    |    |
+|    |    |    |    └── Day of week (0-7, Sunday = 0 or 7)
+|    |    |    └────── Month (1-12)
+|    |    └─────────── Day of month (1-31)
+|    └──────────────── Hour (0-23)
+└───────────────────── Minute (0-59)
+```
+
+Examples:
+- `0 0 * * *` - Every day at midnight
+- `*/15 * * * *` - Every 15 minutes
+- `0 */6 * * *` - Every 6 hours
+- `0 9 * * 1-5` - 9 AM weekdays
+- `0 0 1 * *` - First day of each month
+
+### Headers Configuration
+
+```json
+{
+  "headers": [
+    {
+      "source": "/(.*)",
+      "headers": [
+        { "key": "X-Content-Type-Options", "value": "nosniff" },
+        { "key": "X-Frame-Options", "value": "DENY" },
+        { "key": "X-XSS-Protection", "value": "1; mode=block" },
+        { "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" },
+        { "key": "Permissions-Policy", "value": "camera=(), microphone=(), geolocation=()" }
+      ]
+    }
+  ]
+}
+```
+
+### Rewrites and Redirects
+
+```json
+{
+  "rewrites": [
+    { "source": "/blog/:slug", "destination": "/posts/:slug" },
+    { "source": "/api/v1/:path*", "destination": "/api/:path*" },
+    { "source": "/proxy/:match*", "destination": "https://external.com/:match*" }
+  ],
+  "redirects": [
+    { "source": "/old-page", "destination": "/new-page", "permanent": true },
+    { "source": "/temp-redirect", "destination": "/other", "permanent": false },
+    { "source": "/external", "destination": "https://example.com", "statusCode": 301 }
+  ]
+}
+```
+
+## Next.js Route Segment Config
+
+### Export Options
+
+```typescript
+// Force dynamic rendering
+export const dynamic = 'force-dynamic'
+
+// Force static rendering
+export const dynamic = 'force-static'
+
+// Automatic (default)
+export const dynamic = 'auto'
+
+// Error on dynamic usage
+export const dynamic = 'error'
+```
+
+### Revalidation Options
+
+```typescript
+// Time-based revalidation (seconds)
+export const revalidate = 60
+
+// Disable revalidation (always fresh)
+export const revalidate = 0
+
+// Never revalidate (static)
+export const revalidate = false
+```
+
+### Runtime Options
+
+```typescript
+// Edge runtime
+export const runtime = 'edge'
+
+// Node.js runtime (default)
+export const runtime = 'nodejs'
+```
+
+### Preferred Region
+
+```typescript
+// Single region
+export const preferredRegion = 'iad1'
+
+// Multiple regions
+export const preferredRegion = ['iad1', 'sfo1', 'fra1']
+
+// All regions
+export const preferredRegion = 'auto'
+
+// Home region only
+export const preferredRegion = 'home'
+```
+
+## Fetch Cache Options
+
+```typescript
+// Force cache (default for GET in Server Components)
+fetch(url, { cache: 'force-cache' })
+
+// No cache (always fresh)
+fetch(url, { cache: 'no-store' })
+
+// Time-based revalidation
+fetch(url, { next: { revalidate: 3600 } })
+
+// Tag-based revalidation
+fetch(url, { next: { tags: ['posts', 'featured'] } })
+```
+
+## Response Headers
+
+### Cache-Control Directives
+
+```typescript
+return Response.json(data, {
+  headers: {
+    // Public caching
+    'Cache-Control': 'public, max-age=3600',
+
+    // CDN-only caching
+    'Cache-Control': 'public, s-maxage=3600, max-age=0',
+
+    // Stale-while-revalidate
+    'Cache-Control': 'public, s-maxage=60, stale-while-revalidate=300',
+
+    // No caching
+    'Cache-Control': 'private, no-cache, no-store, must-revalidate',
+
+    // Immutable assets
+    'Cache-Control': 'public, max-age=31536000, immutable'
+  }
+})
+```
+
+### CDN-Specific Headers
+
+```typescript
+return Response.json(data, {
+  headers: {
+    // Vercel-specific CDN cache
+    'CDN-Cache-Control': 'public, max-age=86400',
+
+    // Surrogate control (Varnish/Fastly compatible)
+    'Surrogate-Control': 'max-age=3600',
+
+    // Vary header for content negotiation
+    'Vary': 'Accept-Encoding, Accept-Language'
+  }
+})
+```
+
+## Edge Middleware Matchers
+
+```typescript
+// Match all paths except specific patterns
+export const config = {
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)']
+}
+
+// Match specific paths
+export const config = {
+  matcher: ['/dashboard/:path*', '/api/:path*']
+}
+
+// Match with regex
+export const config = {
+  matcher: [
+    {
+      source: '/api/:path*',
+      regexp: '^/api/(.*)'
+    }
+  ]
+}
+```
+
+## GitHub Actions Secrets
+
+Required secrets for CI/CD integration:
+- `VERCEL_TOKEN` - Vercel API token
+- `VERCEL_ORG_ID` - Organization ID (optional for teams)
+- `VERCEL_PROJECT_ID` - Project ID
+
+Get these values:
+1. `VERCEL_TOKEN`: vercel.com/account/tokens
+2. `VERCEL_ORG_ID`: Run `vercel link` and check `.vercel/project.json`
+3. `VERCEL_PROJECT_ID`: Same as above

moai_adk/templates/.claude/skills/moai-tool-ast-grep/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: "moai-tool-ast-grep"
+description: "AST-based structural code search, security scanning, and refactoring using ast-grep (sg CLI). Supports 40+ languages with pattern matching and code transformation."
+version: 1.2.0
+category: "tool"
+modularized: true
+user-invocable: false
+context: fork
+agent: Explore
+tags: ['ast', 'refactoring', 'code-search', 'lint', 'structural-search', 'security', 'codemod']
+related-skills: ['moai-workflow-testing', 'moai-foundation-quality', 'moai-domain-backend', 'moai-domain-frontend']
+updated: 2026-01-11
+status: "active"
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - mcp__context7__resolve-library-id
+  - mcp__context7__get-library-docs
+---
+
+# AST-Grep Integration
+
+Structural code search, lint, and transformation tool using Abstract Syntax Tree analysis.
+
+## Quick Reference
+
+### What is AST-Grep
+
+AST-Grep (sg) is a fast, polyglot tool for structural code search and transformation. Unlike regex-based search, it understands code syntax and matches patterns based on AST structure.
+
+### When to Use
+
+- Searching for code patterns that regex cannot capture such as nested function calls
+- Refactoring code across multiple files with semantic awareness
+- Security scanning for vulnerability patterns including SQL injection and XSS
+- API migration and deprecation handling
+- Enforcing code style rules at the syntax level
+
+### Core Commands
+
+Pattern search: Execute sg run with pattern option specifying the code pattern to find, lang option for the programming language, and the source directory path.
+
+Security scan with rules: Execute sg scan with config option pointing to your sgconfig.yml file.
+
+Code transformation: Execute sg run with pattern option for the code to find, rewrite option for the replacement, lang option for the language, and source directory path.
+
+Test rules: Execute sg test to validate your rule definitions.
+
+### Pattern Syntax Basics
+
+The dollar sign followed by a variable name such as VAR matches any single AST node and acts as a meta-variable for capturing.
+
+The dollar sign followed by three dollar signs and a variable name such as ARGS matches zero or more nodes using variadic capture.
+
+The double dollar sign followed by underscore matches any single node as an anonymous capture when the value is not needed.
+
+### Supported Languages
+
+Python, JavaScript, TypeScript, Go, Rust, Java, Kotlin, C, C++, Ruby, Swift, C#, PHP, Scala, Elixir, Lua, HTML, Vue, Svelte, and 30+ more.
+
+---
+
+## Implementation Guide
+
+### Installation
+
+For macOS, use brew install ast-grep.
+
+For cross-platform via npm, use npm install -g @ast-grep/cli.
+
+For Rust via Cargo, use cargo install ast-grep.
+
+### Basic Pattern Matching
+
+#### Simple Pattern Search
+
+To find all console.log calls, run sg with pattern console.log($MSG) and lang javascript.
+
+To find all Python function definitions, run sg with pattern def $FUNC($$$ARGS): $$$BODY and lang python.
+
+To find React useState hooks, run sg with pattern useState($INIT) and lang typescriptreact.
+
+#### Meta-variables
+
+Meta-variables capture matching AST nodes in patterns.
+
+Single node capture uses $NAME syntax. For example, pattern const $NAME = require($PATH) captures the variable name and path.
+
+Variadic capture uses $$$ARGS syntax. For example, pattern function $NAME($$$ARGS) captures function name and all arguments.
+
+Anonymous single capture uses $$_ syntax when you need to match but not reference the value.
+
+### Code Transformation
+
+#### Simple Rewrite
+
+To rename a function, run sg with pattern oldFunc($ARGS), rewrite newFunc($ARGS), and lang python.
+
+To update an API call, run sg with pattern axios.get($URL), rewrite fetch($URL), and lang typescript.
+
+#### Complex Transformation with YAML Rules
+
+Create a YAML rule file with the following structure. Set the id field to a unique rule identifier such as convert-var-to-const. Set language to the target language such as javascript. Under the rule section, specify the pattern to match such as var $NAME = $VALUE. Set the fix field to the replacement pattern such as const $NAME = $VALUE. Add a message describing the issue and set severity to warning or error.
+
+Run sg scan with the rule option pointing to your rule file and the source directory.
+
+### Rule-Based Scanning
+
+#### Configuration File
+
+Create an sgconfig.yml file with the following sections. The ruleDirs section lists directories containing rule files such as ./rules/security and ./rules/quality. The testConfigs section specifies test file patterns. The languageGlobs section maps languages to file patterns, mapping python to .py files, typescript to .ts and .tsx files, and javascript to .js and .jsx files.
+
+#### Security Rule Example
+
+Create a security rule file for SQL injection detection. Set the id to sql-injection-risk. Set language to python and severity to error. Write a descriptive message about the vulnerability. Under the rule section, use the any operator to match multiple patterns including cursor.execute with percent formatting, cursor.execute with format method, and cursor.execute with f-string interpolation. Set the fix to show the parameterized query alternative.
+
+### Relational Rules
+
+#### Inside Rule for Scoped Search
+
+Create a rule that searches for console.log calls only inside function declarations. Set the pattern to console.log($$$ARGS) and add an inside constraint with pattern function $NAME($$$PARAMS).
+
+#### Has Rule for Contains Check
+
+Create a rule to find async functions without await. Set the pattern to async function $NAME($$$PARAMS) with a not constraint containing a has rule with pattern await $EXPR. Add message indicating async function without await.
+
+#### Follows and Precedes Rules
+
+Create a rule to detect missing error handling. Set the pattern to match error assignment $ERR := $CALL and add a not constraint with follows rule checking for if $ERR != nil error handling block.
+
+### Composite Rules
+
+Create complex rules using the all operator to combine multiple conditions. For example, combine pattern useState($INIT) with inside constraint for function component and not precedes constraint for useEffect call.
+
+---
+
+## Advanced Patterns
+
+For comprehensive documentation including complex multi-file transformations, custom language configuration, CI/CD integration patterns, and performance optimization tips, see the following module files.
+
+Pattern syntax reference is available in modules/pattern-syntax.md.
+
+Security scanning rule templates are documented in modules/security-rules.md.
+
+Common refactoring patterns are covered in modules/refactoring-patterns.md.
+
+Language-specific patterns are detailed in modules/language-specific.md.
+
+### Context7 Integration
+
+For latest AST-Grep documentation, follow this two-step process.
+
+Step 1: Use mcp__context7__resolve-library-id with query ast-grep to resolve the library identifier.
+
+Step 2: Use mcp__context7__get-library-docs with the resolved library ID to fetch current documentation.
+
+### MoAI-ADK Integration
+
+AST-Grep is integrated into MoAI-ADK through the Tool Registry as AST_ANALYZER type in tool_registry.py, PostToolUse Hook for automatic security scanning after Write/Edit operations, and Permissions with Bash(sg:*) and Bash(ast-grep:*) auto-allowed.
+
+### Running Scans
+
+To scan with MoAI-ADK rules, execute sg scan with config pointing to .claude/skills/moai-tool-ast-grep/rules/sgconfig.yml.
+
+To scan a specific directory, execute sg scan with config sgconfig.yml and the src/ directory.
+
+For JSON output suitable for CI/CD, execute sg scan with config and json flag, redirecting to results.json.
+
+---
+
+## Works Well With
+
+- moai-workflow-testing: TDD integration and test pattern detection
+- moai-foundation-quality: TRUST 5 compliance and code quality gates
+- moai-domain-backend: API pattern detection and security scanning
+- moai-domain-frontend: React/Vue pattern optimization
+- moai-lang-python: Python-specific security and style rules
+- moai-lang-typescript: TypeScript type safety patterns
+
+### Related Agents
+
+- expert-refactoring: AST-based large-scale refactoring
+- expert-security: Security vulnerability scanning
+- manager-quality: Code complexity analysis
+- expert-debug: Pattern-based debugging
+
+---
+
+## Reference
+
+For additional information, consult the AST-Grep Official Documentation at ast-grep.github.io, the AST-Grep GitHub Repository at github.com/ast-grep/ast-grep, the Pattern Playground at ast-grep.github.io/playground.html, and the Rule Configuration Reference at ast-grep.github.io/reference/yaml.html.