flyee 0.1.0

package/core/skills/seo-fundamentals/scripts/seo_checker.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+"""
+SEO Checker - Search Engine Optimization Audit
+Checks HTML/JSX/TSX pages for SEO best practices.
+
+PURPOSE:
+    - Verify meta tags, titles, descriptions
+    - Check Open Graph tags for social sharing
+    - Validate heading hierarchy
+    - Check image accessibility (alt attributes)
+
+WHAT IT CHECKS:
+    - HTML files (actual web pages)
+    - JSX/TSX files (React page components)
+    - Only files that are likely PUBLIC pages
+
+Usage:
+    python seo_checker.py <project_path>
+"""
+import sys
+import json
+import re
+from pathlib import Path
+from datetime import datetime
+
+# Fix Windows console encoding
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except:
+    pass
+
+
+# Directories to skip
+SKIP_DIRS = {
+    'node_modules', '.next', 'dist', 'build', '.git', '.github',
+    '__pycache__', '.vscode', '.idea', 'coverage', 'test', 'tests',
+    '__tests__', 'spec', 'docs', 'documentation', 'examples'
+}
+
+# Files to skip (not pages)
+SKIP_PATTERNS = [
+    'config', 'setup', 'util', 'helper', 'hook', 'context', 'store',
+    'service', 'api', 'lib', 'constant', 'type', 'interface', 'mock',
+    '.test.', '.spec.', '_test.', '_spec.'
+]
+
+
+def is_page_file(file_path: Path) -> bool:
+    """Check if this file is likely a public-facing page."""
+    name = file_path.name.lower()
+    stem = file_path.stem.lower()
+    
+    # Skip utility/config files
+    if any(skip in name for skip in SKIP_PATTERNS):
+        return False
+    
+    # Check path - pages in specific directories are likely pages
+    parts = [p.lower() for p in file_path.parts]
+    page_dirs = ['pages', 'app', 'routes', 'views', 'screens']
+    
+    if any(d in parts for d in page_dirs):
+        return True
+    
+    # Filename indicators for pages
+    page_names = ['page', 'index', 'home', 'about', 'contact', 'blog', 
+                  'post', 'article', 'product', 'landing', 'layout']
+    
+    if any(p in stem for p in page_names):
+        return True
+    
+    # HTML files are usually pages
+    if file_path.suffix.lower() in ['.html', '.htm']:
+        return True
+    
+    return False
+
+
+def find_pages(project_path: Path) -> list:
+    """Find page files to check."""
+    patterns = ['**/*.html', '**/*.htm', '**/*.jsx', '**/*.tsx']
+    
+    files = []
+    for pattern in patterns:
+        for f in project_path.glob(pattern):
+            # Skip excluded directories
+            if any(skip in f.parts for skip in SKIP_DIRS):
+                continue
+            
+            # Check if it's likely a page
+            if is_page_file(f):
+                files.append(f)
+    
+    return files[:50]  # Limit to 50 files
+
+
+def check_page(file_path: Path) -> dict:
+    """Check a single page for SEO issues."""
+    issues = []
+    
+    try:
+        content = file_path.read_text(encoding='utf-8', errors='ignore')
+    except Exception as e:
+        return {"file": str(file_path.name), "issues": [f"Error: {e}"]}
+    
+    # Detect if this is a layout/template file (has Head component)
+    is_layout = 'Head>' in content or '<head' in content.lower()
+    
+    # 1. Title tag
+    has_title = '<title' in content.lower() or 'title=' in content or 'Head>' in content
+    if not has_title and is_layout:
+        issues.append("Missing <title> tag")
+    
+    # 2. Meta description
+    has_description = 'name="description"' in content.lower() or 'name=\'description\'' in content.lower()
+    if not has_description and is_layout:
+        issues.append("Missing meta description")
+    
+    # 3. Open Graph tags
+    has_og = 'og:' in content or 'property="og:' in content.lower()
+    if not has_og and is_layout:
+        issues.append("Missing Open Graph tags")
+    
+    # 4. Heading hierarchy - multiple H1s
+    h1_matches = re.findall(r'<h1[^>]*>', content, re.I)
+    if len(h1_matches) > 1:
+        issues.append(f"Multiple H1 tags ({len(h1_matches)})")
+    
+    # 5. Images without alt
+    img_pattern = r'<img[^>]+>'
+    imgs = re.findall(img_pattern, content, re.I)
+    for img in imgs:
+        if 'alt=' not in img.lower():
+            issues.append("Image missing alt attribute")
+            break
+        if 'alt=""' in img or "alt=''" in img:
+            issues.append("Image has empty alt attribute")
+            break
+    
+    # 6. Check for canonical link (nice to have)
+    # has_canonical = 'rel="canonical"' in content.lower()
+    
+    return {
+        "file": str(file_path.name),
+        "issues": issues
+    }
+
+
+def main():
+    project_path = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
+    
+    print(f"\n{'='*60}")
+    print(f"  SEO CHECKER - Search Engine Optimization Audit")
+    print(f"{'='*60}")
+    print(f"Project: {project_path}")
+    print(f"Time: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    print("-"*60)
+    
+    # Find pages
+    pages = find_pages(project_path)
+    
+    if not pages:
+        print("\n[!] No page files found.")
+        print("    Looking for: HTML, JSX, TSX in pages/app/routes directories")
+        output = {"script": "seo_checker", "files_checked": 0, "passed": True}
+        print("\n" + json.dumps(output, indent=2))
+        sys.exit(0)
+    
+    print(f"Found {len(pages)} page files to analyze\n")
+    
+    # Check each page
+    all_issues = []
+    for f in pages:
+        result = check_page(f)
+        if result["issues"]:
+            all_issues.append(result)
+    
+    # Summary
+    print("=" * 60)
+    print("SEO ANALYSIS RESULTS")
+    print("=" * 60)
+    
+    if all_issues:
+        # Group by issue type
+        issue_counts = {}
+        for item in all_issues:
+            for issue in item["issues"]:
+                issue_counts[issue] = issue_counts.get(issue, 0) + 1
+        
+        print("\nIssue Summary:")
+        for issue, count in sorted(issue_counts.items(), key=lambda x: -x[1]):
+            print(f"  [{count}] {issue}")
+        
+        print(f"\nAffected files ({len(all_issues)}):")
+        for item in all_issues[:5]:
+            print(f"  - {item['file']}")
+        if len(all_issues) > 5:
+            print(f"  ... and {len(all_issues) - 5} more")
+    else:
+        print("\n[OK] No SEO issues found!")
+    
+    total_issues = sum(len(item["issues"]) for item in all_issues)
+    passed = total_issues == 0
+    
+    output = {
+        "script": "seo_checker",
+        "project": str(project_path),
+        "files_checked": len(pages),
+        "files_with_issues": len(all_issues),
+        "issues_found": total_issues,
+        "passed": passed
+    }
+    
+    print("\n" + json.dumps(output, indent=2))
+    
+    sys.exit(0 if passed else 1)
+
+
+if __name__ == "__main__":
+    main()

package/core/skills/server-management/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: server-management
+description: Server management principles and decision-making. Process management, monitoring strategy, and scaling decisions. Teaches thinking, not commands.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Server Management
+
+> Server management principles for production operations.
+> **Learn to THINK, not memorize commands.**
+
+---
+
+## 1. Process Management Principles
+
+### Tool Selection
+
+| Scenario | Tool |
+|----------|------|
+| **Node.js app** | PM2 (clustering, reload) |
+| **Any app** | systemd (Linux native) |
+| **Containers** | Docker/Podman |
+| **Orchestration** | Kubernetes, Docker Swarm |
+
+### Process Management Goals
+
+| Goal | What It Means |
+|------|---------------|
+| **Restart on crash** | Auto-recovery |
+| **Zero-downtime reload** | No service interruption |
+| **Clustering** | Use all CPU cores |
+| **Persistence** | Survive server reboot |
+
+---
+
+## 2. Monitoring Principles
+
+### What to Monitor
+
+| Category | Key Metrics |
+|----------|-------------|
+| **Availability** | Uptime, health checks |
+| **Performance** | Response time, throughput |
+| **Errors** | Error rate, types |
+| **Resources** | CPU, memory, disk |
+
+### Alert Severity Strategy
+
+| Level | Response |
+|-------|----------|
+| **Critical** | Immediate action |
+| **Warning** | Investigate soon |
+| **Info** | Review daily |
+
+### Monitoring Tool Selection
+
+| Need | Options |
+|------|---------|
+| Simple/Free | PM2 metrics, htop |
+| Full observability | Grafana, Datadog |
+| Error tracking | Sentry |
+| Uptime | UptimeRobot, Pingdom |
+
+---
+
+## 3. Log Management Principles
+
+### Log Strategy
+
+| Log Type | Purpose |
+|----------|---------|
+| **Application logs** | Debug, audit |
+| **Access logs** | Traffic analysis |
+| **Error logs** | Issue detection |
+
+### Log Principles
+
+1. **Rotate logs** to prevent disk fill
+2. **Structured logging** (JSON) for parsing
+3. **Appropriate levels** (error/warn/info/debug)
+4. **No sensitive data** in logs
+
+---
+
+## 4. Scaling Decisions
+
+### When to Scale
+
+| Symptom | Solution |
+|---------|----------|
+| High CPU | Add instances (horizontal) |
+| High memory | Increase RAM or fix leak |
+| Slow response | Profile first, then scale |
+| Traffic spikes | Auto-scaling |
+
+### Scaling Strategy
+
+| Type | When to Use |
+|------|-------------|
+| **Vertical** | Quick fix, single instance |
+| **Horizontal** | Sustainable, distributed |
+| **Auto** | Variable traffic |
+
+---
+
+## 5. Health Check Principles
+
+### What Constitutes Healthy
+
+| Check | Meaning |
+|-------|---------|
+| **HTTP 200** | Service responding |
+| **Database connected** | Data accessible |
+| **Dependencies OK** | External services reachable |
+| **Resources OK** | CPU/memory not exhausted |
+
+### Health Check Implementation
+
+- Simple: Just return 200
+- Deep: Check all dependencies
+- Choose based on load balancer needs
+
+---
+
+## 6. Security Principles
+
+| Area | Principle |
+|------|-----------|
+| **Access** | SSH keys only, no passwords |
+| **Firewall** | Only needed ports open |
+| **Updates** | Regular security patches |
+| **Secrets** | Environment vars, not files |
+| **Audit** | Log access and changes |
+
+---
+
+## 7. Troubleshooting Priority
+
+When something's wrong:
+
+1. **Check if running** (process status)
+2. **Check logs** (error messages)
+3. **Check resources** (disk, memory, CPU)
+4. **Check network** (ports, DNS)
+5. **Check dependencies** (database, APIs)
+
+---
+
+## 8. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Run as root | Use non-root user |
+| Ignore logs | Set up log rotation |
+| Skip monitoring | Monitor from day one |
+| Manual restarts | Auto-restart config |
+| No backups | Regular backup schedule |
+
+---
+
+> **Remember:** A well-managed server is boring. That's the goal.

package/core/skills/session-resilience/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: session-resilience
+description: Crash recovery and session persistence. Lock files, continue protocol, crash detection and automatic resume. Absorbed from GSD-2 crash-recovery.ts patterns.
+---
+
+# Session Resilience
+
+> **Absorbed from:** GSD-2 `crash-recovery.ts`, `session-lock.ts`, `continue.md`
+> **Purpose:** Never lose work. Detect crashes. Resume exactly where you stopped.
+
+---
+
+## 🎯 PURPOSE
+
+AI coding sessions can be interrupted by:
+- Token limits reached
+- Connection drops
+- IDE restarts
+- User closes terminal
+
+Without resilience, all context is lost. The agent starts over, potentially:
+- Re-doing completed work
+- Missing where it left off
+- Forgetting decisions made
+
+---
+
+## 🔒 SESSION LOCK
+
+**File:** `.flyee/session-lock.json` (gitignored)
+
+Written when agent starts working. Deleted on clean exit.
+
+```json
+{
+  "pid": 12345,
+  "startedAt": "2026-03-31T17:00:00Z",
+  "runtime": "antigravity",
+  "activeSprint": "S09",
+  "activePhase": "P02",
+  "activeTask": "T03",
+  "lastAction": "Implementing BlogCard component",
+  "lastUpdate": "2026-03-31T17:30:00Z"
+}
+```
+
+### Lock Lifecycle
+
+```
+Session Start → Check for orphan lock
+  ├── No lock → Acquire lock → Work
+  └── Lock exists → Check PID alive?
+      ├── PID alive → Another session running. WARN user.
+      └── PID dead → CRASH DETECTED
+          → Read continue.md
+          → Display crash info
+          → Resume from continue point
+          → Clear old lock, acquire new
+```
+
+### Crash Detection
+
+If `session-lock.json` exists AND the PID is dead:
+```
+⚠️ Previous session was interrupted.
+  Sprint: S09 | Phase: P02 | Task: T03
+  Last action: Implementing BlogCard component
+  Crashed at: 2026-03-31T17:30:00Z
+
+  Resuming from continue.md...
+```
+
+---
+
+## 📝 CONTINUE PROTOCOL
+
+**File:** `.flyee/sprints/S{NN}/phases/P{NN}/continue.md` (gitignored)
+
+Written when:
+- Agent detects it's approaching token/context limits
+- Agent is about to be interrupted (explicit stop)
+- After completing a significant sub-step within a task
+
+Deleted after successful resume.
+
+### Continue File Format
+
+```markdown
+---
+sprint: S09
+phase: P02
+task: T03
+step: 4
+total_steps: 7
+saved_at: 2026-03-31T17:30:00Z
+reason: approaching_context_limit
+---
+
+## Completed Work
+- BlogCard component skeleton created (`src/components/BlogCard.tsx`)
+- Props interface defined (Post type)
+- Basic layout with title and excerpt
+
+## Pending Work
+- [ ] Connect to usePosts hook (step 5)
+- [ ] Implement responsive image handling (step 6)
+- [ ] Add hover animation per design tokens (step 7)
+
+## Decisions Made This Session
+- Using CSS Modules (not Tailwind) — consistent with project
+- Image: next/image with blur placeholder
+
+## Files Modified
+- `src/components/BlogCard.tsx` — created (87 lines)
+- `src/components/BlogCard.module.css` — created (42 lines)
+
+## Context for Next Session
+The BlogCard renders static data. Need to wire it to the usePosts()
+hook which calls GET /api/posts. The hook already exists in
+`src/hooks/usePosts.ts` from T02.
+
+## Next Action
+Import usePosts hook in BlogList page and pass posts array to BlogCard.
+```
+
+### When to Write continue.md
+
+| Trigger | Action |
+|---------|--------|
+| Token/context limit approaching | Write continue.md with full state |
+| User says "stop" or "pause" | Write continue.md |
+| After completing a task step | Update continue.md (overwrite) |
+| Task fully completed | DELETE continue.md |
+| Phase completed | DELETE all continue.md in phase |
+
+### Resume Protocol
+
+```
+1. Read continue.md
+2. Display summary to user:
+   "Resuming S09/P02/T03 — step 4/7.
+    ✅ BlogCard skeleton done
+    📋 Next: connect usePosts hook"
+3. Load ONLY the files listed in "Files Modified"
+4. Continue from "Next Action"
+5. Delete continue.md
+6. Acquire new session lock
+```
+
+---
+
+## 🛡️ ATOMIC WRITES
+
+All state file writes use atomic pattern:
+1. Write to `.flyee/temp-{random}`
+2. Rename to target file
+3. This prevents corruption if process dies mid-write
+
+```python
+# In bridge.py / scripts
+import tempfile, os
+
+def atomic_write(filepath, content):
+    dir = os.path.dirname(filepath)
+    fd, tmp = tempfile.mkstemp(dir=dir, prefix='flyee-tmp-')
+    try:
+        os.write(fd, content.encode('utf-8'))
+        os.close(fd)
+        os.rename(tmp, filepath)
+    except:
+        os.close(fd)
+        os.unlink(tmp)
+        raise
+```
+
+---
+
+## ⚡ QUICK REFERENCE
+
+### Agent Session Start Checklist
+
+```
+1. [ ] Check .flyee/session-lock.json
+   - Exists + PID dead? → Crash recovery
+   - Exists + PID alive? → Warn "another session active"
+   - Not exists? → Normal start
+2. [ ] Read .flyee/STATE.md → know where you are
+3. [ ] Check continue.md in active phase → resume if exists
+4. [ ] Acquire session lock
+5. [ ] Begin work
+```
+
+### Agent Session End Checklist
+
+```
+1. [ ] Write continue.md if mid-task
+2. [ ] Update STATE.md
+3. [ ] Release session lock (delete session-lock.json)
+```