@macpaw/cctk 1.0.0-beta.1

package/templates/claude/skills/devops/references/docker-compose.md

@@ -0,0 +1,292 @@
+# Docker Compose
+
+Multi-container application orchestration.
+
+## Basic Structure
+
+```yaml
+version: '3.8'
+
+services:
+  web:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+      - DATABASE_URL=postgresql://user:pass@db:5432/app
+    depends_on:
+      - db
+      - redis
+    volumes:
+      - ./src:/app/src
+    networks:
+      - app-network
+    restart: unless-stopped
+
+  db:
+    image: postgres:15-alpine
+    environment:
+      POSTGRES_USER: user
+      POSTGRES_PASSWORD: pass
+      POSTGRES_DB: app
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    networks:
+      - app-network
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U user"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  redis:
+    image: redis:7-alpine
+    networks:
+      - app-network
+    volumes:
+      - redis_data:/data
+
+volumes:
+  postgres_data:
+  redis_data:
+
+networks:
+  app-network:
+    driver: bridge
+```
+
+## Commands
+
+```bash
+# Start services
+docker compose up
+docker compose up -d
+
+# Build images before starting
+docker compose up --build
+
+# Scale service
+docker compose up -d --scale web=3
+
+# Stop services
+docker compose down
+
+# Stop and remove volumes
+docker compose down --volumes
+
+# Logs
+docker compose logs
+docker compose logs -f web
+
+# Execute command
+docker compose exec web sh
+docker compose exec db psql -U user -d app
+
+# List services
+docker compose ps
+
+# Restart service
+docker compose restart web
+
+# Pull images
+docker compose pull
+
+# Validate
+docker compose config
+```
+
+## Environment-Specific Configs
+
+**compose.yml (base):**
+```yaml
+services:
+  web:
+    build: .
+    ports:
+      - "3000:3000"
+```
+
+**compose.override.yml (dev, auto-loaded):**
+```yaml
+services:
+  web:
+    volumes:
+      - ./src:/app/src  # Live reload
+    environment:
+      - NODE_ENV=development
+      - DEBUG=true
+    command: npm run dev
+```
+
+**compose.prod.yml (production):**
+```yaml
+services:
+  web:
+    image: registry.example.com/myapp:1.0
+    restart: always
+    environment:
+      - NODE_ENV=production
+    deploy:
+      replicas: 3
+      resources:
+        limits:
+          cpus: '0.5'
+          memory: 512M
+```
+
+**Usage:**
+```bash
+# Development (uses compose.yml + compose.override.yml)
+docker compose up
+
+# Production
+docker compose -f compose.yml -f compose.prod.yml up -d
+```
+
+## Health Checks
+
+```yaml
+services:
+  web:
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
+      interval: 30s
+      timeout: 3s
+      start_period: 40s
+      retries: 3
+```
+
+## Resource Limits
+
+```yaml
+services:
+  web:
+    deploy:
+      resources:
+        limits:
+          cpus: '0.5'
+          memory: 512M
+        reservations:
+          cpus: '0.25'
+          memory: 256M
+```
+
+## Logging
+
+```yaml
+services:
+  web:
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
+```
+
+## Environment Variables
+
+**Using .env file (local development only):**
+```bash
+# .env (never commit — add to .gitignore)
+DATABASE_URL=postgresql://user:pass@db:5432/app
+NODE_ENV=development
+```
+
+```yaml
+services:
+  web:
+    env_file:
+      - .env
+```
+
+## Networking
+
+Services on same network communicate via service name:
+
+```yaml
+services:
+  web:
+    depends_on:
+      - db
+    environment:
+      # Use service name as hostname
+      - DATABASE_URL=postgresql://user:pass@db:5432/app
+```
+
+## Volume Backup/Restore
+
+```bash
+# Backup
+docker compose run --rm -v app_data:/data -v $(pwd):/backup \
+  alpine tar czf /backup/backup.tar.gz /data
+
+# Restore
+docker compose run --rm -v app_data:/data -v $(pwd):/backup \
+  alpine tar xzf /backup/backup.tar.gz -C /data
+```
+
+## Common Stacks
+
+### Web + Database + Cache
+```yaml
+services:
+  web:
+    build: .
+    depends_on:
+      - db
+      - redis
+  db:
+    image: postgres:15-alpine
+  redis:
+    image: redis:7-alpine
+```
+
+### Microservices
+```yaml
+services:
+  api-gateway:
+    build: ./gateway
+  user-service:
+    build: ./services/users
+  order-service:
+    build: ./services/orders
+  rabbitmq:
+    image: rabbitmq:3-management
+```
+
+## Best Practices
+
+- Use named volumes for data persistence
+- Implement health checks for all services
+- Set restart policies for production
+- Use environment-specific compose files
+- Configure resource limits
+- Enable logging with size limits
+- Use depends_on for service ordering
+- Network isolation with custom networks
+
+## Troubleshooting
+
+```bash
+# View service logs
+docker compose logs -f service-name
+
+# Check service status
+docker compose ps
+
+# Restart specific service
+docker compose restart service-name
+
+# Rebuild service
+docker compose up --build service-name
+
+# Remove everything
+docker compose down --volumes --rmi all
+```
+
+## Resources
+
+- Docs: https://docs.docker.com/compose/
+- Compose Specification: https://docs.docker.com/compose/compose-file/
+- Best Practices: https://docs.docker.com/compose/production/

package/templates/claude/skills/devops/references/gcloud-platform.md

@@ -0,0 +1,307 @@
+# Google Cloud Platform with gcloud CLI
+
+Comprehensive guide for gcloud CLI - command-line interface for Google Cloud Platform.
+
+## Installation
+
+### Linux
+```bash
+curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-linux-x86_64.tar.gz
+tar -xf google-cloud-cli-linux-x86_64.tar.gz
+./google-cloud-sdk/install.sh
+./google-cloud-sdk/bin/gcloud init
+```
+
+### Debian/Ubuntu
+```bash
+echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list
+sudo apt-get update && sudo apt-get install google-cloud-cli
+```
+
+### macOS
+```bash
+curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-darwin-arm.tar.gz
+tar -xf google-cloud-cli-darwin-arm.tar.gz
+./google-cloud-sdk/install.sh
+```
+
+## Authentication
+
+### User Account
+```bash
+# Login with browser
+gcloud auth login
+
+# Login without browser (remote/headless)
+gcloud auth login --no-browser
+
+# List accounts
+gcloud auth list
+
+# Switch account
+gcloud config set account user@example.com
+```
+
+### Service Account
+
+> **SECURITY:** Avoid creating SA key files. Use service account impersonation (below) instead.
+> Key files on disk are a security risk — prefer short-lived credentials via impersonation.
+
+```bash
+# Create service account (no key file needed with impersonation)
+gcloud iam service-accounts create SA_NAME \
+  --display-name="Service Account"
+
+# Grant role
+gcloud projects add-iam-policy-binding PROJECT_ID \
+  --member="serviceAccount:SA_EMAIL" \
+  --role="roles/compute.admin"
+```
+
+### Service Account Impersonation (Recommended)
+```bash
+# Impersonate for single command
+gcloud compute instances list \
+  --impersonate-service-account=SA_EMAIL
+
+# Set default impersonation
+gcloud config set auth/impersonate_service_account SA_EMAIL
+
+# Clear impersonation
+gcloud config unset auth/impersonate_service_account
+```
+
+Why impersonation? Short-lived credentials, no key files, centralized management.
+
+## Configuration Management
+
+### Named Configurations
+```bash
+# Create configuration
+gcloud config configurations create dev
+
+# List configurations
+gcloud config configurations list
+
+# Activate configuration
+gcloud config configurations activate dev
+
+# Set properties
+gcloud config set project my-project-dev
+gcloud config set compute/region us-central1
+gcloud config set compute/zone us-central1-a
+
+# View properties
+gcloud config list
+
+# Delete configuration
+gcloud config configurations delete dev
+```
+
+### Multi-Environment Pattern
+```bash
+# Development
+gcloud config configurations create dev
+gcloud config set project my-project-dev
+gcloud config set account dev@example.com
+
+# Staging
+gcloud config configurations create staging
+gcloud config set project my-project-staging
+gcloud config set auth/impersonate_service_account staging-sa@project.iam.gserviceaccount.com
+
+# Production
+gcloud config configurations create prod
+gcloud config set project my-project-prod
+gcloud config set auth/impersonate_service_account prod-sa@project.iam.gserviceaccount.com
+```
+
+## Project Management
+
+```bash
+# List projects
+gcloud projects list
+
+# Create project
+gcloud projects create PROJECT_ID --name="Project Name"
+
+# Set active project
+gcloud config set project PROJECT_ID
+
+# Get current project
+gcloud config get-value project
+
+# Enable API
+gcloud services enable compute.googleapis.com
+gcloud services enable container.googleapis.com
+
+# List enabled APIs
+gcloud services list
+```
+
+## Output Formats
+
+```bash
+# JSON (recommended for scripting)
+gcloud compute instances list --format=json
+
+# YAML
+gcloud compute instances list --format=yaml
+
+# CSV
+gcloud compute instances list --format="csv(name,zone,status)"
+
+# Value (single field)
+gcloud config get-value project --format="value()"
+
+# Custom table
+gcloud compute instances list \
+  --format="table(name,zone,machineType,status)"
+```
+
+## Filtering
+
+```bash
+# Server-side filtering (efficient)
+gcloud compute instances list --filter="zone:us-central1-a"
+gcloud compute instances list --filter="status=RUNNING"
+gcloud compute instances list --filter="name~^web-.*"
+
+# Multiple conditions
+gcloud compute instances list \
+  --filter="zone:us-central1 AND status=RUNNING"
+
+# Negation
+gcloud compute instances list --filter="NOT status=TERMINATED"
+```
+
+## CI/CD Integration
+
+> **Note:** CI/CD runners use Workload Identity Federation (keyless) when possible.
+> SA key JSON is a legacy pattern for CI runners only — never for interactive agent sessions.
+
+### GitHub Actions (Workload Identity Federation — Recommended)
+```yaml
+name: Deploy to GCP
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - id: auth
+        uses: google-github-actions/auth@v2
+        with:
+          workload_identity_provider: projects/PROJECT_NUM/locations/global/workloadIdentityPools/POOL/providers/PROVIDER
+          service_account: SA_EMAIL
+
+      - name: Set up Cloud SDK
+        uses: google-github-actions/setup-gcloud@v2
+
+      - name: Deploy
+        run: |
+          gcloud run deploy my-service \
+            --image=gcr.io/${{ vars.GCP_PROJECT_ID }}/my-image \
+            --region=us-central1
+```
+
+### GitLab CI (Workload Identity Federation)
+```yaml
+deploy:
+  image: google/cloud-sdk:alpine
+  id_tokens:
+    GITLAB_OIDC_TOKEN:
+      aud: https://iam.googleapis.com/projects/PROJECT_NUM/locations/global/workloadIdentityPools/POOL/providers/PROVIDER
+  script:
+    - gcloud iam workload-identity-pools create-cred-config PROVIDER_RESOURCE
+        --service-account=SA_EMAIL
+        --output-file=credentials.json
+        --credential-source-type=text
+    - export GOOGLE_APPLICATION_CREDENTIALS=credentials.json
+    - gcloud config set project $GCP_PROJECT_ID
+    - gcloud app deploy
+  only:
+    - main
+```
+
+## Best Practices
+
+### Security
+- Never commit or hardcode credentials
+- Use `gcloud auth login` (OAuth) for interactive sessions
+- Use service account impersonation — avoid SA key files
+- Use Workload Identity Federation for CI/CD (keyless)
+- Grant minimal IAM permissions
+
+### Performance
+- Use server-side filtering: `--filter`
+- Limit output: `--limit=10`
+- Project only needed fields: `--format="value(name)"`
+- Batch operations with `--async`
+
+### Maintainability
+- Use named configurations for environments
+- Document commands
+- Implement error handling and retries
+
+## Troubleshooting
+
+```bash
+# Check authentication
+gcloud auth list
+
+# Re-authenticate
+gcloud auth login
+gcloud auth application-default login
+
+# Check IAM permissions
+gcloud projects get-iam-policy PROJECT_ID \
+  --flatten="bindings[].members" \
+  --filter="bindings.members:user@example.com"
+
+# View configuration
+gcloud config list
+
+# Reset configuration
+gcloud config configurations delete default
+gcloud init
+```
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Initialize | `gcloud init` |
+| Login | `gcloud auth login` |
+| Set project | `gcloud config set project PROJECT_ID` |
+| List resources | `gcloud [SERVICE] list` |
+| Create resource | `gcloud [SERVICE] create RESOURCE` |
+| Delete resource | `gcloud [SERVICE] delete RESOURCE` |
+| Get help | `gcloud [SERVICE] --help` |
+
+## Global Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--project` | Override project |
+| `--format` | Output format (json, yaml, csv) |
+| `--filter` | Server-side filter |
+| `--limit` | Limit results |
+| `--quiet` | Suppress prompts |
+| `--verbosity` | Log level (debug, info, warning, error) |
+| `--async` | Don't wait for operation |
+
+## Resources
+
+- gcloud Reference: https://cloud.google.com/sdk/gcloud/reference
+- Installation: https://cloud.google.com/sdk/docs/install
+- Authentication: https://cloud.google.com/docs/authentication
+- Cheatsheet: https://cloud.google.com/sdk/docs/cheatsheet