thachvd-kit 1.0.0

package/scripts/session_manager.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""
+Session Manager - Antigravity Kit
+=================================
+Analyzes project state, detects tech stack, tracks file statistics, and provides
+a summary of the current session.
+
+Usage:
+    python .agent/scripts/session_manager.py status [path]
+    python .agent/scripts/session_manager.py info [path]
+"""
+
+import os
+import json
+import argparse
+from pathlib import Path
+from typing import Dict, Any, List
+
+def get_project_root(path: str) -> Path:
+    return Path(path).resolve()
+
+def analyze_package_json(root: Path) -> Dict[str, Any]:
+    pkg_file = root / "package.json"
+    if not pkg_file.exists():
+        return {"type": "unknown", "dependencies": {}}
+    
+    try:
+        with open(pkg_file, 'r', encoding='utf-8') as f:
+            data = json.load(f)
+            
+        deps = data.get("dependencies", {})
+        dev_deps = data.get("devDependencies", {})
+        all_deps = {**deps, **dev_deps}
+        
+        stack = []
+        if "next" in all_deps: stack.append("Next.js")
+        elif "react" in all_deps: stack.append("React")
+        elif "vue" in all_deps: stack.append("Vue")
+        elif "svelte" in all_deps: stack.append("Svelte")
+        elif "express" in all_deps: stack.append("Express")
+        elif "nestjs" in all_deps or "@nestjs/core" in all_deps: stack.append("NestJS")
+        
+        if "tailwindcss" in all_deps: stack.append("Tailwind CSS")
+        if "prisma" in all_deps: stack.append("Prisma")
+        if "typescript" in all_deps: stack.append("TypeScript")
+        
+        return {
+            "name": data.get("name", "unnamed"),
+            "version": data.get("version", "0.0.0"),
+            "stack": stack,
+            "scripts": list(data.get("scripts", {}).keys())
+        }
+    except Exception as e:
+        return {"error": str(e)}
+
+def count_files(root: Path) -> Dict[str, int]:
+    stats = {"created": 0, "modified": 0, "total": 0}
+    # Simple count for now, comprehensive tracking would require git diff or extensive history
+    exclude = {".git", "node_modules", ".next", "dist", "build", ".agent", ".gemini", "__pycache__"}
+    
+    for root_dir, dirs, files in os.walk(root):
+        dirs[:] = [d for d in dirs if d not in exclude]
+        stats["total"] += len(files)
+        
+    return stats
+
+def detect_features(root: Path) -> List[str]:
+    # Heuristic: look at folder names in src/
+    features = []
+    src = root / "src"
+    if src.exists():
+        possible_dirs = ["components", "modules", "features", "app", "pages", "services"]
+        for d in possible_dirs:
+            p = src / d
+            if p.exists() and p.is_dir():
+                # List subdirectories as likely features
+                for child in p.iterdir():
+                    if child.is_dir():
+                        features.append(child.name)
+    return features[:10] # Limit to top 10
+
+def print_status(root: Path):
+    info = analyze_package_json(root)
+    stats = count_files(root)
+    features = detect_features(root)
+    
+    print("\n=== Project Status ===")
+    print(f"\n📁 Project: {info.get('name', root.name)}")
+    print(f"📂 Path: {root}")
+    print(f"🏷️  Type: {', '.join(info.get('stack', ['Generic']))}")
+    print(f"📊 Status: Active")
+    
+    print("\n🔧 Tech Stack:")
+    for tech in info.get('stack', []):
+        print(f"   • {tech}")
+        
+    print(f"\n✅ Detected Modules/Features ({len(features)}):")
+    for feat in features:
+        print(f"   • {feat}")
+    if not features:
+        print("   (No distinct feature modules detected)")
+        
+    print(f"\n📄 Files: {stats['total']} total files tracked")
+    print("\n====================\n")
+
+def main():
+    parser = argparse.ArgumentParser(description="Session Manager")
+    parser.add_argument("command", choices=["status", "info"], help="Command to run")
+    parser.add_argument("path", nargs="?", default=".", help="Project path")
+    
+    args = parser.parse_args()
+    root = get_project_root(args.path)
+    
+    if args.command == "status":
+        print_status(root)
+    elif args.command == "info":
+        print(json.dumps(analyze_package_json(root), indent=2))
+
+if __name__ == "__main__":
+    main()

package/scripts/verify_all.py

@@ -0,0 +1,327 @@
+#!/usr/bin/env python3
+"""
+Full Verification Suite - Antigravity Kit
+==========================================
+
+Runs COMPLETE validation including all checks + performance + E2E.
+Use this before deployment or major releases.
+
+Usage:
+    python scripts/verify_all.py . --url <URL>
+
+Includes ALL checks:
+    ✅ Security Scan (OWASP, secrets, dependencies)
+    ✅ Lint & Type Coverage
+    ✅ Schema Validation
+    ✅ Test Suite (unit + integration)
+    ✅ UX Audit (psychology, accessibility)
+    ✅ SEO Check
+    ✅ Lighthouse (Core Web Vitals)
+    ✅ Playwright E2E
+    ✅ Bundle Analysis (if applicable)
+    ✅ Mobile Audit (if applicable)
+"""
+
+import sys
+import subprocess
+import argparse
+from pathlib import Path
+from typing import List, Dict, Optional
+from datetime import datetime
+
+# ANSI colors
+class Colors:
+    HEADER = '\033[95m'
+    BLUE = '\033[94m'
+    CYAN = '\033[96m'
+    GREEN = '\033[92m'
+    YELLOW = '\033[93m'
+    RED = '\033[91m'
+    ENDC = '\033[0m'
+    BOLD = '\033[1m'
+
+def print_header(text: str):
+    print(f"\n{Colors.BOLD}{Colors.CYAN}{'='*70}{Colors.ENDC}")
+    print(f"{Colors.BOLD}{Colors.CYAN}{text.center(70)}{Colors.ENDC}")
+    print(f"{Colors.BOLD}{Colors.CYAN}{'='*70}{Colors.ENDC}\n")
+
+def print_step(text: str):
+    print(f"{Colors.BOLD}{Colors.BLUE}🔄 {text}{Colors.ENDC}")
+
+def print_success(text: str):
+    print(f"{Colors.GREEN}✅ {text}{Colors.ENDC}")
+
+def print_warning(text: str):
+    print(f"{Colors.YELLOW}⚠️  {text}{Colors.ENDC}")
+
+def print_error(text: str):
+    print(f"{Colors.RED}❌ {text}{Colors.ENDC}")
+
+# Complete verification suite
+VERIFICATION_SUITE = [
+    # P0: Security (CRITICAL)
+    {
+        "category": "Security",
+        "checks": [
+            ("Security Scan", ".agent/skills/vulnerability-scanner/scripts/security_scan.py", True),
+            ("Dependency Analysis", ".agent/skills/vulnerability-scanner/scripts/dependency_analyzer.py", False),
+        ]
+    },
+    
+    # P1: Code Quality (CRITICAL)
+    {
+        "category": "Code Quality",
+        "checks": [
+            ("Lint Check", ".agent/skills/lint-and-validate/scripts/lint_runner.py", True),
+            ("Type Coverage", ".agent/skills/lint-and-validate/scripts/type_coverage.py", False),
+        ]
+    },
+    
+    # P2: Data Layer
+    {
+        "category": "Data Layer",
+        "checks": [
+            ("Schema Validation", ".agent/skills/database-design/scripts/schema_validator.py", False),
+        ]
+    },
+    
+    # P3: Testing
+    {
+        "category": "Testing",
+        "checks": [
+            ("Test Suite", ".agent/skills/testing-patterns/scripts/test_runner.py", False),
+        ]
+    },
+    
+    # P4: UX & Accessibility
+    {
+        "category": "UX & Accessibility",
+        "checks": [
+            ("UX Audit", ".agent/skills/frontend-design/scripts/ux_audit.py", False),
+            ("Accessibility Check", ".agent/skills/frontend-design/scripts/accessibility_checker.py", False),
+        ]
+    },
+    
+    # P5: SEO & Content
+    {
+        "category": "SEO & Content",
+        "checks": [
+            ("SEO Check", ".agent/skills/seo-fundamentals/scripts/seo_checker.py", False),
+            ("GEO Check", ".agent/skills/geo-fundamentals/scripts/geo_checker.py", False),
+        ]
+    },
+    
+    # P6: Performance (requires URL)
+    {
+        "category": "Performance",
+        "requires_url": True,
+        "checks": [
+            ("Lighthouse Audit", ".agent/skills/performance-profiling/scripts/lighthouse_audit.py", True),
+            ("Bundle Analysis", ".agent/skills/performance-profiling/scripts/bundle_analyzer.py", False),
+        ]
+    },
+    
+    # P7: E2E Testing (requires URL)
+    {
+        "category": "E2E Testing",
+        "requires_url": True,
+        "checks": [
+            ("Playwright E2E", ".agent/skills/webapp-testing/scripts/playwright_runner.py", False),
+        ]
+    },
+    
+    # P8: Mobile (if applicable)
+    {
+        "category": "Mobile",
+        "checks": [
+            ("Mobile Audit", ".agent/skills/mobile-design/scripts/mobile_audit.py", False),
+        ]
+    },
+    
+    # P9: Internationalization
+    {
+        "category": "Internationalization",
+        "checks": [
+            ("i18n Check", ".agent/skills/i18n-localization/scripts/i18n_checker.py", False),
+        ]
+    },
+]
+
+def run_script(name: str, script_path: Path, project_path: str, url: Optional[str] = None) -> dict:
+    """Run validation script"""
+    if not script_path.exists():
+        print_warning(f"{name}: Script not found, skipping")
+        return {"name": name, "passed": True, "skipped": True, "duration": 0}
+    
+    print_step(f"Running: {name}")
+    start_time = datetime.now()
+    
+    # Build command
+    cmd = ["python", str(script_path), project_path]
+    if url and ("lighthouse" in script_path.name.lower() or "playwright" in script_path.name.lower()):
+        cmd.append(url)
+    
+    # Run
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=600  # 10 minute timeout for slow checks
+        )
+        
+        duration = (datetime.now() - start_time).total_seconds()
+        passed = result.returncode == 0
+        
+        if passed:
+            print_success(f"{name}: PASSED ({duration:.1f}s)")
+        else:
+            print_error(f"{name}: FAILED ({duration:.1f}s)")
+            if result.stderr:
+                print(f"  {result.stderr[:300]}")
+        
+        return {
+            "name": name,
+            "passed": passed,
+            "output": result.stdout,
+            "error": result.stderr,
+            "skipped": False,
+            "duration": duration
+        }
+    
+    except subprocess.TimeoutExpired:
+        duration = (datetime.now() - start_time).total_seconds()
+        print_error(f"{name}: TIMEOUT (>{duration:.0f}s)")
+        return {"name": name, "passed": False, "skipped": False, "duration": duration, "error": "Timeout"}
+    
+    except Exception as e:
+        duration = (datetime.now() - start_time).total_seconds()
+        print_error(f"{name}: ERROR - {str(e)}")
+        return {"name": name, "passed": False, "skipped": False, "duration": duration, "error": str(e)}
+
+def print_final_report(results: List[dict], start_time: datetime):
+    """Print comprehensive final report"""
+    total_duration = (datetime.now() - start_time).total_seconds()
+    
+    print_header("📊 FULL VERIFICATION REPORT")
+    
+    # Statistics
+    total = len(results)
+    passed = sum(1 for r in results if r["passed"] and not r.get("skipped"))
+    failed = sum(1 for r in results if not r["passed"] and not r.get("skipped"))
+    skipped = sum(1 for r in results if r.get("skipped"))
+    
+    print(f"Total Duration: {total_duration:.1f}s")
+    print(f"Total Checks: {total}")
+    print(f"{Colors.GREEN}✅ Passed: {passed}{Colors.ENDC}")
+    print(f"{Colors.RED}❌ Failed: {failed}{Colors.ENDC}")
+    print(f"{Colors.YELLOW}⏭️  Skipped: {skipped}{Colors.ENDC}")
+    print()
+    
+    # Category breakdown
+    print(f"{Colors.BOLD}Results by Category:{Colors.ENDC}")
+    current_category = None
+    for r in results:
+        # Print category header if changed
+        if r.get("category") and r["category"] != current_category:
+            current_category = r["category"]
+            print(f"\n{Colors.BOLD}{Colors.CYAN}{current_category}:{Colors.ENDC}")
+        
+        # Print result
+        if r.get("skipped"):
+            status = f"{Colors.YELLOW}⏭️ {Colors.ENDC}"
+        elif r["passed"]:
+            status = f"{Colors.GREEN}✅{Colors.ENDC}"
+        else:
+            status = f"{Colors.RED}❌{Colors.ENDC}"
+        
+        duration_str = f"({r.get('duration', 0):.1f}s)" if not r.get("skipped") else ""
+        print(f"  {status} {r['name']} {duration_str}")
+    
+    print()
+    
+    # Failed checks detail
+    if failed > 0:
+        print(f"{Colors.BOLD}{Colors.RED}❌ FAILED CHECKS:{Colors.ENDC}")
+        for r in results:
+            if not r["passed"] and not r.get("skipped"):
+                print(f"\n{Colors.RED}✗ {r['name']}{Colors.ENDC}")
+                if r.get("error"):
+                    error_preview = r["error"][:200]
+                    print(f"  Error: {error_preview}")
+        print()
+    
+    # Final verdict
+    if failed > 0:
+        print_error(f"VERIFICATION FAILED - {failed} check(s) need attention")
+        print(f"\n{Colors.YELLOW}💡 Tip: Fix critical (security, lint) issues first{Colors.ENDC}")
+        return False
+    else:
+        print_success("✨ ALL CHECKS PASSED - Ready for deployment! ✨")
+        return True
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Run complete Antigravity Kit verification suite",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  python scripts/verify_all.py . --url http://localhost:3000
+  python scripts/verify_all.py . --url https://staging.example.com --no-e2e
+        """
+    )
+    parser.add_argument("project", help="Project path to validate")
+    parser.add_argument("--url", required=True, help="URL for performance & E2E checks")
+    parser.add_argument("--no-e2e", action="store_true", help="Skip E2E tests")
+    parser.add_argument("--stop-on-fail", action="store_true", help="Stop on first failure")
+    
+    args = parser.parse_args()
+    
+    project_path = Path(args.project).resolve()
+    
+    if not project_path.exists():
+        print_error(f"Project path does not exist: {project_path}")
+        sys.exit(1)
+    
+    print_header("🚀 ANTIGRAVITY KIT - FULL VERIFICATION SUITE")
+    print(f"Project: {project_path}")
+    print(f"URL: {args.url}")
+    print(f"Started: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    
+    start_time = datetime.now()
+    results = []
+    
+    # Run all verification categories
+    for suite in VERIFICATION_SUITE:
+        category = suite["category"]
+        requires_url = suite.get("requires_url", False)
+        
+        # Skip if requires URL and not provided
+        if requires_url and not args.url:
+            continue
+        
+        # Skip E2E if flag set
+        if args.no_e2e and category == "E2E Testing":
+            continue
+        
+        print_header(f"📋 {category.upper()}")
+        
+        for name, script_path, required in suite["checks"]:
+            script = project_path / script_path
+            result = run_script(name, script, str(project_path), args.url)
+            result["category"] = category
+            results.append(result)
+            
+            # Stop on critical failure if flag set
+            if args.stop_on_fail and required and not result["passed"] and not result.get("skipped"):
+                print_error(f"CRITICAL: {name} failed. Stopping verification.")
+                print_final_report(results, start_time)
+                sys.exit(1)
+    
+    # Print final report
+    all_passed = print_final_report(results, start_time)
+    
+    sys.exit(0 if all_passed else 1)
+
+if __name__ == "__main__":
+    main()

package/skills/api-design/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: api-design
+description: REST API design patterns. Use when designing new API endpoints, reviewing API contracts, choosing pagination strategies, error response formats, versioning, or HTTP status codes.
+allowed-tools: Read, Edit, Write
+---
+
+# API Design Patterns
+
+## URL Structure
+
+```
+# Resources: plural nouns, lowercase, kebab-case, no verbs
+GET    /api/v1/users
+POST   /api/v1/users
+GET    /api/v1/users/:id
+PUT    /api/v1/users/:id
+PATCH  /api/v1/users/:id
+DELETE /api/v1/users/:id
+
+# Sub-resources for relationships
+GET    /api/v1/users/:id/orders
+POST   /api/v1/users/:id/orders
+
+# Actions that don't map to CRUD
+POST   /api/v1/orders/:id/cancel
+POST   /api/v1/auth/refresh
+```
+
+**Naming rules:**
+```
+✅ /api/v1/team-members          kebab-case
+✅ /api/v1/orders?status=active  query params for filtering
+✅ /api/v1/users/123/orders      nested for ownership
+
+❌ /api/v1/getUsers              verb in URL
+❌ /api/v1/user                  singular
+❌ /api/v1/team_members          snake_case in URLs
+```
+
+## HTTP Methods and Status Codes
+
+| Method | Idempotent | Use For |
+|--------|-----------|---------|
+| GET | Yes | Retrieve |
+| POST | No | Create / trigger actions |
+| PUT | Yes | Full replacement |
+| PATCH | No | Partial update |
+| DELETE | Yes | Remove |
+
+```
+# Success
+200 OK                    GET, PUT, PATCH (with body)
+201 Created               POST (add Location header)
+204 No Content            DELETE, PUT (no body)
+
+# Client Errors
+400 Bad Request           Validation failure, malformed JSON
+401 Unauthorized          Missing or invalid auth
+403 Forbidden             Authenticated, not authorized
+404 Not Found             Resource doesn't exist
+409 Conflict              Duplicate entry, state conflict
+422 Unprocessable Entity  Valid JSON, semantically invalid
+429 Too Many Requests     Rate limit exceeded
+
+# Server Errors
+500 Internal Server Error Never expose internal details
+503 Service Unavailable   Include Retry-After header
+```
+
+## Response Format
+
+```json
+// Success
+{ "data": { "id": "abc-123", "email": "alice@example.com", "created_at": "2025-01-15T10:30:00Z" } }
+
+// Collection with pagination
+{
+  "data": [{ "id": "abc-123", "name": "Alice" }],
+  "meta": { "total": 142, "page": 1, "per_page": 20, "total_pages": 8 },
+  "links": { "next": "/api/v1/users?page=2&per_page=20" }
+}
+
+// Error
+{
+  "error": {
+    "code": "validation_error",
+    "message": "Request validation failed",
+    "details": [
+      { "field": "email", "message": "Must be a valid email", "code": "invalid_format" }
+    ]
+  }
+}
+```
+
+## Pagination
+
+| Use Case | Type |
+|----------|------|
+| Admin dashboards, small datasets (<10K) | Offset |
+| Infinite scroll, feeds, large datasets | **Cursor** |
+| Public APIs | Cursor (default) |
+| Search results | Offset (users expect page numbers) |
+
+```
+# Offset
+GET /api/v1/users?page=2&per_page=20
+
+# Cursor
+GET /api/v1/users?cursor=eyJpZCI6MTIzfQ&limit=20
+→ { "data": [...], "meta": { "has_next": true, "next_cursor": "eyJpZCI6MTQzfQ" } }
+```
+
+## Versioning
+
+```
+/api/v1/users     ← recommended
+/api/v2/users     ← when breaking changes needed
+```
+
+**Breaking changes** (require new version): removing fields, changing types, changing URL structure.
+**Non-breaking** (no new version): adding optional fields/params, adding endpoints.
+
+Deprecation: 6-month notice, add `Sunset` header, return `410 Gone` after.
+
+## Filtering, Sorting, Search
+
+```
+GET /api/v1/orders?status=active&created_after=2025-01-01
+GET /api/v1/users?sort=created_at&order=desc
+GET /api/v1/products?q=widget
+GET /api/v1/users?fields=id,email,name      # Sparse fieldsets
+```
+
+## Rate Limiting Headers
+
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 45
+X-RateLimit-Reset: 1640995200
+Retry-After: 30    # on 429
+```
+
+## API Design Checklist
+
+Before shipping a new endpoint:
+
+- [ ] URL: plural noun, kebab-case, no verbs
+- [ ] Correct HTTP method and status code
+- [ ] Input validated with schema (Zod, Pydantic, Go validator)
+- [ ] Error response follows standard format with field-level details
+- [ ] Pagination implemented for list endpoints
+- [ ] Authentication required (or explicitly marked public)
+- [ ] Authorization checked (user can only access their own resources)
+- [ ] Rate limiting configured
+- [ ] Response does not leak internal details (stack traces, SQL errors)
+- [ ] OpenAPI spec updated

package/skills/api-patterns/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: api-patterns
+description: API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# API Patterns
+
+> API design principles and decision-making for 2025.
+> **Learn to THINK, not copy fixed patterns.**
+
+## 🎯 Selective Reading Rule
+
+**Read ONLY files relevant to the request!** Check the content map, find what you need.
+
+---
+
+## 📑 Content Map
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| `api-style.md` | REST vs GraphQL vs tRPC decision tree | Choosing API type |
+| `rest.md` | Resource naming, HTTP methods, status codes | Designing REST API |
+| `response.md` | Envelope pattern, error format, pagination | Response structure |
+| `graphql.md` | Schema design, when to use, security | Considering GraphQL |
+| `trpc.md` | TypeScript monorepo, type safety | TS fullstack projects |
+| `versioning.md` | URI/Header/Query versioning | API evolution planning |
+| `auth.md` | JWT, OAuth, Passkey, API Keys | Auth pattern selection |
+| `rate-limiting.md` | Token bucket, sliding window | API protection |
+| `documentation.md` | OpenAPI/Swagger best practices | Documentation |
+| `security-testing.md` | OWASP API Top 10, auth/authz testing | Security audits |
+
+---
+
+## 🔗 Related Skills
+
+| Need | Skill |
+|------|-------|
+| API implementation | `@[skills/backend-development]` |
+| Data structure | `@[skills/database-design]` |
+| Security details | `@[skills/security-hardening]` |
+
+---
+
+## ✅ Decision Checklist
+
+Before designing an API:
+
+- [ ] **Asked user about API consumers?**
+- [ ] **Chosen API style for THIS context?** (REST/GraphQL/tRPC)
+- [ ] **Defined consistent response format?**
+- [ ] **Planned versioning strategy?**
+- [ ] **Considered authentication needs?**
+- [ ] **Planned rate limiting?**
+- [ ] **Documentation approach defined?**
+
+---
+
+## ❌ Anti-Patterns
+
+**DON'T:**
+- Default to REST for everything
+- Use verbs in REST endpoints (/getUsers)
+- Return inconsistent response formats
+- Expose internal errors to clients
+- Skip rate limiting
+
+**DO:**
+- Choose API style based on context
+- Ask about client requirements
+- Document thoroughly
+- Use appropriate status codes
+
+---
+
+## Script
+
+| Script | Purpose | Command |
+|--------|---------|---------|
+| `scripts/api_validator.py` | API endpoint validation | `python scripts/api_validator.py <project_path>` |
+