specweave 0.1.0

package/src/skills/hetzner-provisioner/README.md

@@ -0,0 +1,308 @@
+**Name:** hetzner-provisioner
+**Type:** Infrastructure / DevOps
+**Model:** Claude Sonnet 4 (balanced for IaC generation)
+**Status:** Planned
+
+---
+
+## Overview
+
+Automated Hetzner Cloud infrastructure provisioning using Terraform or Pulumi. Generates production-ready IaC code for deploying SaaS applications at $10-15/month instead of $50-100/month on Vercel/AWS.
+
+## When This Skill Activates
+
+**Keywords**: deploy on Hetzner, Hetzner Cloud, budget deployment, cheap hosting, $10/month, cost-effective infrastructure
+
+**Example prompts**:
+- "Deploy my NextJS app on Hetzner"
+- "I want the cheapest possible hosting for my SaaS"
+- "Set up infrastructure on Hetzner Cloud with Postgres"
+- "Deploy for under $15/month"
+
+## What It Generates
+
+### 1. Terraform Configuration
+
+**main.tf**:
+```hcl
+terraform {
+  required_providers {
+    hcloud = {
+      source = "hetznercloud/hcloud"
+      version = "~> 1.45"
+    }
+  }
+}
+
+provider "hcloud" {
+  token = var.hcloud_token
+}
+
+# Server instance
+resource "hcloud_server" "app" {
+  name        = "my-saas-app"
+  server_type = "cx11"
+  image       = "ubuntu-22.04"
+  location    = "nbg1"  # Nuremberg, Germany
+
+  user_data = file("${path.module}/cloud-init.yaml")
+
+  public_net {
+    ipv4_enabled = true
+    ipv6_enabled = true
+  }
+}
+
+# Managed Postgres database
+resource "hcloud_database" "postgres" {
+  name              = "my-saas-db"
+  engine            = "postgresql"
+  version           = "15"
+  size              = "db-1x-small"
+  location          = "nbg1"
+}
+
+# Firewall
+resource "hcloud_firewall" "app" {
+  name = "my-saas-firewall"
+
+  rule {
+    direction = "in"
+    protocol  = "tcp"
+    port      = "80"
+    source_ips = ["0.0.0.0/0", "::/0"]
+  }
+
+  rule {
+    direction = "in"
+    protocol  = "tcp"
+    port      = "443"
+    source_ips = ["0.0.0.0/0", "::/0"]
+  }
+
+  rule {
+    direction = "in"
+    protocol  = "tcp"
+    port      = "22"
+    source_ips = ["0.0.0.0/0", "::/0"]  # Restrict to your IP in production
+  }
+}
+
+# Apply firewall to server
+resource "hcloud_firewall_attachment" "app" {
+  firewall_id = hcloud_firewall.app.id
+  server_ids  = [hcloud_server.app.id]
+}
+
+# Output deployment info
+output "server_ip" {
+  value = hcloud_server.app.ipv4_address
+}
+
+output "database_host" {
+  value = hcloud_database.postgres.host
+}
+
+output "database_port" {
+  value = hcloud_database.postgres.port
+}
+```
+
+### 2. Docker Configuration
+
+**Dockerfile**:
+```dockerfile
+FROM node:20-alpine AS base
+
+# Dependencies
+FROM base AS deps
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+
+# Builder
+FROM base AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+
+# Runner
+FROM base AS runner
+WORKDIR /app
+ENV NODE_ENV production
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nextjs
+
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+USER nextjs
+
+EXPOSE 3000
+ENV PORT 3000
+
+CMD ["node", "server.js"]
+```
+
+### 3. GitHub Actions CI/CD
+
+**.github/workflows/deploy.yml**:
+```yaml
+name: Deploy to Hetzner
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Terraform
+        uses: hashicorp/setup-terraform@v3
+
+      - name: Terraform Init
+        run: terraform init
+        working-directory: ./terraform
+        env:
+          HCLOUD_TOKEN: ${{ secrets.HETZNER_API_TOKEN }}
+
+      - name: Terraform Plan
+        run: terraform plan
+        working-directory: ./terraform
+        env:
+          HCLOUD_TOKEN: ${{ secrets.HETZNER_API_TOKEN }}
+
+      - name: Terraform Apply
+        run: terraform apply -auto-approve
+        working-directory: ./terraform
+        env:
+          HCLOUD_TOKEN: ${{ secrets.HETZNER_API_TOKEN }}
+
+      - name: Build and Deploy Docker
+        run: |
+          ssh ${{ secrets.SERVER_USER }}@${{ secrets.SERVER_IP }} << 'EOF'
+            cd /app
+            git pull
+            docker-compose build
+            docker-compose up -d
+          EOF
+```
+
+### 4. SSL Configuration (Let's Encrypt)
+
+**nginx.conf** (auto-generated):
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name your-domain.com;
+
+    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
+
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_cache_bypass $http_upgrade;
+    }
+}
+```
+
+## Cost Breakdown
+
+### Small SaaS (100-1000 users)
+- **CX11** (1 vCPU, 2GB RAM): $5.83/month
+- **Managed Postgres** (2GB): $5.00/month
+- **Storage** (20GB): $0.50/month
+- **SSL** (Let's Encrypt): Free
+- **Total**: ~$11.33/month
+
+### Medium SaaS (1000-10000 users)
+- **CX21** (2 vCPU, 4GB RAM): $6.90/month
+- **Managed Postgres** (4GB): $10.00/month
+- **Storage** (40GB): $1.00/month
+- **Total**: ~$18/month
+
+### Large SaaS (10000+ users)
+- **CX31** (2 vCPU, 8GB RAM): $14.28/month
+- **Managed Postgres** (8GB): $20.00/month
+- **Storage** (80GB): $2.00/month
+- **Total**: ~$36/month
+
+## Test Cases
+
+### Test 1: Basic Provision
+**File**: `test-cases/test-1-basic-provision.yaml`
+**Scenario**: Provision CX11 instance with Docker
+**Expected**: Terraform code generated, cost ~$6/month
+
+### Test 2: Postgres Provision
+**File**: `test-cases/test-2-postgres-provision.yaml`
+**Scenario**: Add managed Postgres database
+**Expected**: Database resource added, cost ~$11/month
+
+### Test 3: SSL Configuration
+**File**: `test-cases/test-3-ssl-config.yaml`
+**Scenario**: Configure SSL with Let's Encrypt
+**Expected**: Nginx + Certbot configuration, HTTPS working
+
+## Verification Steps
+
+See `test-results/README.md` for:
+1. How to run each test case
+2. Expected vs actual output
+3. Manual verification steps
+4. Screenshots of successful deployment
+
+## Integration with Other Skills
+
+- **cost-optimizer**: Recommends Hetzner when budget <$20/month
+- **devops-agent**: Provides strategic infrastructure planning
+- **nextjs-agent**: NextJS-specific deployment configuration
+- **nodejs-backend**: Node.js app deployment
+- **monitoring-setup**: Adds Uptime Kuma monitoring
+
+## Limitations
+
+- **EU-only**: Data centers in Germany/Finland (GDPR-friendly but not global)
+- **No auto-scaling**: Manual scaling only (upgrade instance type)
+- **Single-region**: Multi-region requires manual setup
+- **No serverless**: Traditional VM-based hosting
+
+## Alternatives
+
+When NOT to use Hetzner:
+- **Global audience**: Use Vercel (global edge network)
+- **Auto-scaling needed**: Use AWS/GCP
+- **Serverless preferred**: Use Vercel/Netlify
+- **Enterprise SLA required**: Use AWS/Azure with support plans
+
+## Future Enhancements
+
+- [ ] Kubernetes (k3s) cluster setup
+- [ ] Load balancer configuration
+- [ ] Multi-region deployment
+- [ ] Auto-scaling with Hetzner Cloud API
+- [ ] Monitoring integration (Grafana + Prometheus)
+- [ ] Disaster recovery automation
+
+---
+
+**Status**: Planned (Increment 003)
+**Priority**: P1
+**Tests**: 3+ test cases required
+**Documentation**: `.specweave/docs/guides/hetzner-deployment.md`

package/src/skills/hetzner-provisioner/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: hetzner-provisioner
+description: Provisions infrastructure on Hetzner Cloud with Terraform/Pulumi. Generates IaC code for CX11/CX21/CX31 instances, managed Postgres, SSL configuration, Docker deployment. Activates for deploy on Hetzner, Hetzner Cloud, budget deployment, cheap hosting, $10/month hosting.
+---
+
+# Hetzner Cloud Provisioner
+
+Automated infrastructure provisioning for Hetzner Cloud - the budget-friendly alternative to Vercel and AWS.
+
+## Purpose
+
+Generate and deploy infrastructure-as-code (Terraform/Pulumi) for Hetzner Cloud, enabling $10-15/month SaaS deployments instead of $50-100/month on other platforms.
+
+## When to Use
+
+Activates when user mentions:
+- "deploy on Hetzner"
+- "Hetzner Cloud"
+- "budget deployment"
+- "cheap hosting"
+- "deploy for $10/month"
+- "cost-effective infrastructure"
+
+## What It Does
+
+1. **Analyzes requirements**:
+   - Application type (NextJS, Node.js, Python, etc.)
+   - Database needs (Postgres, MySQL, Redis)
+   - Expected traffic/users
+   - Budget constraints
+
+2. **Generates Infrastructure-as-Code**:
+   - Terraform configuration for Hetzner Cloud
+   - Alternative: Pulumi for TypeScript-native IaC
+   - Server instances (CX11, CX21, CX31)
+   - Managed databases (Postgres, MySQL)
+   - Object storage (if needed)
+   - Networking (firewall rules, floating IPs)
+
+3. **Configures Production Setup**:
+   - Docker containerization
+   - SSL certificates (Let's Encrypt)
+   - DNS configuration (Cloudflare or Hetzner DNS)
+   - GitHub Actions CI/CD pipeline
+   - Monitoring (Uptime Kuma, self-hosted)
+   - Automated backups
+
+4. **Outputs Deployment Guide**:
+   - Step-by-step deployment instructions
+   - Cost breakdown
+   - Monitoring URLs
+   - Troubleshooting guide
+
+---
+
+## ⚠️ CRITICAL: Secrets Required (MANDATORY CHECK)
+
+**BEFORE generating Terraform/Pulumi code, CHECK for Hetzner API token.**
+
+### Step 1: Check If Token Exists
+
+```bash
+# Check .env file
+if [ -f .env ] && grep -q "HETZNER_API_TOKEN" .env; then
+  echo "✅ Hetzner API token found"
+else
+  # Token NOT found - STOP and prompt user
+fi
+```
+
+### Step 2: If Token Missing, STOP and Show This Message
+
+```
+🔐 **Hetzner API Token Required**
+
+I need your Hetzner API token to provision infrastructure.
+
+**How to get it**:
+1. Go to: https://console.hetzner.cloud/
+2. Click on your project (or create one)
+3. Navigate to: Security → API Tokens
+4. Click "Generate API Token"
+5. Give it a name (e.g., "specweave-deployment")
+6. Permissions: **Read & Write**
+7. Click "Generate"
+8. **Copy the token immediately** (you can't see it again!)
+
+**Where I'll save it**:
+- File: `.env` (gitignored, secure)
+- Format: `HETZNER_API_TOKEN=your-token-here`
+
+**Security**:
+✅ .env is in .gitignore (never committed to git)
+✅ Token is 64 characters, alphanumeric
+✅ Stored locally only (not in source code)
+
+Please paste your Hetzner API token:
+```
+
+### Step 3: Validate Token Format
+
+```bash
+# Hetzner tokens are 64 alphanumeric characters
+if [[ ! "$HETZNER_API_TOKEN" =~ ^[a-zA-Z0-9]{64}$ ]]; then
+  echo "⚠️  Warning: Token format unexpected"
+  echo "Expected: 64 alphanumeric characters"
+  echo "Got: ${#HETZNER_API_TOKEN} characters"
+  echo ""
+  echo "This might not be a valid Hetzner API token."
+  echo "Continue anyway? (yes/no)"
+fi
+```
+
+### Step 4: Save Token Securely
+
+```bash
+# Save to .env
+echo "HETZNER_API_TOKEN=$HETZNER_API_TOKEN" >> .env
+
+# Ensure .env is gitignored
+if ! grep -q "^\.env$" .gitignore; then
+  echo ".env" >> .gitignore
+fi
+
+# Create .env.example for team
+cat > .env.example << 'EOF'
+# Hetzner Cloud API Token
+# Get from: https://console.hetzner.cloud/ → Security → API Tokens
+HETZNER_API_TOKEN=your-hetzner-token-here
+EOF
+
+echo "✅ Token saved to .env (gitignored)"
+echo "✅ Created .env.example for team (commit this)"
+```
+
+### Step 5: Use Token in Terraform
+
+```hcl
+# terraform/variables.tf
+variable "hetzner_token" {
+  description = "Hetzner Cloud API Token"
+  type        = string
+  sensitive   = true
+}
+
+# terraform/provider.tf
+provider "hcloud" {
+  token = var.hetzner_token
+}
+
+# Run Terraform
+# export TF_VAR_hetzner_token=$HETZNER_API_TOKEN
+# terraform apply
+```
+
+---
+
+## Example Usage
+
+**User**: "Deploy my NextJS app on Hetzner with Postgres, as cheaply as possible"
+
+**hetzner-provisioner**:
+```markdown
+I'll provision your NextJS app on Hetzner Cloud for ~$12/month.
+
+Infrastructure:
+- CX11 instance (2 vCPU, 2GB RAM): $5.83/month
+- Managed Postgres (2GB): $5.00/month
+- 20GB storage: $0.50/month
+- SSL (Let's Encrypt): Free
+- Total: ~$11.33/month
+
+Creating Terraform configuration...
+
+✅ Generated files:
+- terraform/main.tf
+- terraform/variables.tf
+- terraform/outputs.tf
+- .github/workflows/deploy.yml
+
+Next steps:
+1. Set HETZNER_API_TOKEN in GitHub secrets
+2. Push to GitHub
+3. GitHub Actions will deploy automatically
+
+Deployment URL: https://your-app.yourdomain.com (after DNS configured)
+```
+
+## Configuration
+
+Supports multiple instance types:
+- **CX11** (1 vCPU, 2GB RAM): $5.83/month - Small apps, 100-1000 users
+- **CX21** (2 vCPU, 4GB RAM): $6.90/month - Medium apps, 1000-10000 users
+- **CX31** (2 vCPU, 8GB RAM): $14.28/month - Larger apps, 10000+ users
+
+Database options:
+- Managed Postgres (2GB): $5/month
+- Managed MySQL (2GB): $5/month
+- Self-hosted (included in instance cost)
+
+## Test Cases
+
+See `test-cases/` for validation scenarios:
+1. **test-1-basic-provision.yaml** - Basic CX11 instance
+2. **test-2-postgres-provision.yaml** - Add managed Postgres
+3. **test-3-ssl-config.yaml** - SSL and DNS configuration
+
+## Cost Comparison
+
+| Platform | Small App | Medium App | Large App |
+|----------|-----------|------------|-----------|
+| **Hetzner** | $12/mo | $15/mo | $25/mo |
+| Vercel | $60/mo | $120/mo | $240/mo |
+| AWS | $25/mo | $80/mo | $200/mo |
+| Railway | $20/mo | $50/mo | $100/mo |
+
+**Savings**: 50-80% vs alternatives
+
+## Technical Details
+
+**Terraform Provider**: `hetznercloud/hcloud`
+**API**: Hetzner Cloud API v1
+**Regions**: Nuremberg, Falkenstein, Helsinki (Germany/Finland)
+**Deployment**: Docker + GitHub Actions
+**Monitoring**: Uptime Kuma (self-hosted, free)
+
+## Integration
+
+Works with:
+- `cost-optimizer` - Recommends Hetzner when budget-conscious
+- `devops-agent` - Strategic infrastructure planning
+- `nextjs-agent` - NextJS-specific deployment
+- Any backend framework (Node.js, Python, Go, etc.)
+
+## Limitations
+
+- EU-only data centers (GDPR-friendly)
+- Requires Hetzner Cloud account
+- Manual DNS configuration needed
+- Not suitable for multi-region deployments (use AWS/GCP for that)
+
+## Future Enhancements
+
+- Kubernetes support (k3s on Hetzner)
+- Load balancer configuration
+- Multi-region deployment
+- Disaster recovery setup
+
+---
+
+**For detailed usage**, see `README.md` and test cases in `test-cases/`

package/src/skills/hetzner-provisioner/test-cases/test-1-basic-provision.yaml

@@ -0,0 +1,71 @@
+---
+name: "Basic Hetzner CX11 Provisioning"
+description: "Provision a basic CX11 instance with Docker for NextJS app deployment"
+skill: hetzner-provisioner
+priority: P1
+estimated_time: "5-10 minutes"
+
+input:
+  prompt: "Deploy my NextJS app on Hetzner as cheaply as possible"
+  requirements:
+    app_type: nextjs
+    instance_type: cx11
+    database: none
+    ssl: false
+    budget: "$10/month"
+
+expected_output:
+  terraform_files_generated:
+    - main.tf
+    - variables.tf
+    - outputs.tf
+    - cloud-init.yaml
+
+  terraform_resources:
+    - type: hcloud_server
+      name: app
+      server_type: cx11
+      image: ubuntu-22.04
+      location: nbg1
+
+    - type: hcloud_firewall
+      name: app
+      rules:
+        - port: 80
+        - port: 443
+        - port: 22
+
+  dockerfile_generated: true
+
+  github_actions_workflow: true
+
+  cost_estimate:
+    monthly: "$5.83"
+    breakdown:
+      - "CX11 instance: $5.83/month"
+      - "Storage (20GB): $0.50/month"
+    total: "$6.33/month"
+    within_budget: true
+
+  deployment_guide:
+    steps:
+      - "Set HETZNER_API_TOKEN in GitHub secrets"
+      - "Push code to GitHub"
+      - "GitHub Actions will deploy automatically"
+      - "Access app at http://[SERVER_IP]:3000"
+
+validation:
+  - "terraform validate passes without errors"
+  - "main.tf contains hcloud_server resource"
+  - "Dockerfile exists and is valid"
+  - "Cost estimate under $10/month"
+  - "GitHub Actions workflow file exists"
+
+expected_errors: []
+
+success_criteria:
+  - "All Terraform files generated"
+  - "Cost within budget"
+  - "Deployment guide provided"
+  - "No validation errors"
+---

package/src/skills/hetzner-provisioner/test-cases/test-2-postgres-provision.yaml

@@ -0,0 +1,85 @@
+---
+name: "Hetzner Provisioning with Managed Postgres"
+description: "Provision CX11 instance + managed Postgres database for full-stack app"
+skill: hetzner-provisioner
+priority: P1
+estimated_time: "10-15 minutes"
+
+input:
+  prompt: "Deploy my NextJS app on Hetzner with Postgres database"
+  requirements:
+    app_type: nextjs
+    instance_type: cx11
+    database: postgres
+    database_size: "2GB"
+    ssl: false
+    budget: "$15/month"
+
+expected_output:
+  terraform_files_generated:
+    - main.tf
+    - variables.tf
+    - outputs.tf
+    - cloud-init.yaml
+    - database.tf
+
+  terraform_resources:
+    - type: hcloud_server
+      name: app
+      server_type: cx11
+
+    - type: hcloud_database
+      name: postgres
+      engine: postgresql
+      version: "15"
+      size: db-1x-small
+
+    - type: hcloud_firewall
+      name: app
+
+  environment_variables:
+    - DATABASE_URL: "postgresql://user:pass@[DB_HOST]:5432/dbname"
+    - POSTGRES_HOST: "[DB_HOST from terraform output]"
+    - POSTGRES_PORT: "5432"
+    - POSTGRES_DB: "my_saas_db"
+
+  dockerfile_generated: true
+
+  docker_compose_generated: true
+  docker_compose_services:
+    - app
+    - (database managed separately by Hetzner)
+
+  cost_estimate:
+    monthly: "$10.83"
+    breakdown:
+      - "CX11 instance: $5.83/month"
+      - "Managed Postgres (2GB): $5.00/month"
+      - "Storage (20GB): $0.50/month"
+    total: "$11.33/month"
+    within_budget: true
+
+  deployment_guide:
+    steps:
+      - "Set HETZNER_API_TOKEN in GitHub secrets"
+      - "Set database credentials in environment variables"
+      - "Run terraform apply to provision infrastructure"
+      - "Database will be accessible at terraform output"
+      - "Configure app DATABASE_URL"
+      - "Deploy app with GitHub Actions"
+
+validation:
+  - "terraform validate passes"
+  - "hcloud_database resource exists in main.tf or database.tf"
+  - "Database connection string in outputs.tf"
+  - "Environment variables documented"
+  - "Cost under $15/month"
+
+expected_errors: []
+
+success_criteria:
+  - "Managed Postgres provisioned"
+  - "Connection string outputted"
+  - "Cost within budget"
+  - "App can connect to database"
+---