packwise-skills 1.0.0

package/sub-skills/cloud/ci-cd-pipelines.md

@@ -0,0 +1,350 @@
+# CI/CD Pipeline Build Sub-Skill
+
+Set up continuous integration and continuous deployment pipelines for building, testing, and publishing software packages.
+
+**Current versions**: GitHub Actions / GitLab CI / Jenkins (2025-2026)
+
+## When to Use
+
+- Automated build on every push/tag
+- Automated testing before merge
+- Automated publishing to package registries
+- Multi-platform build (build on Linux/macOS/Windows)
+- Release automation (tag → build → publish → notify)
+
+---
+
+## GitHub Actions (Recommended for GitHub-hosted projects)
+
+### Basic Build + Test
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run lint
+      - run: npm test
+      - run: npm run build
+```
+
+### Multi-Platform Build
+
+```yaml
+# .github/workflows/release.yml
+name: Release
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - run: npm ci
+      - run: npm run build
+      - run: npm run package  # electron-builder, tauri, etc.
+      - uses: actions/upload-artifact@v4
+        with:
+          name: build-${{ matrix.os }}
+          path: release/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: artifacts/
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: artifacts/**/*
+          generate_release_notes: true
+```
+
+### Container Build + Push
+
+```yaml
+# .github/workflows/docker.yml
+name: Docker
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/build-push-action@v6
+        with:
+          push: true
+          tags: ghcr.io/${{ github.repository }}:${{ github.ref_name }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+```
+
+### Release to Package Registries
+
+```yaml
+# npm publish
+- run: npm publish --provenance --access public
+  env:
+    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+# PyPI publish
+- uses: pypa/gh-action-pypi-publish@release/v1
+  with:
+    password: ${{ secrets.PYPI_API_TOKEN }}
+
+# crates.io publish
+- run: cargo publish
+  env:
+    CARGO_REGISTRY_TOKEN: ${{ secrets.CRATES_TOKEN }}
+
+# Docker Hub
+- uses: docker/login-action@v3
+  with:
+    username: ${{ secrets.DOCKER_USERNAME }}
+    password: ${{ secrets.DOCKER_TOKEN }}
+```
+
+---
+
+## GitLab CI
+
+### Basic Pipeline
+
+```yaml
+# .gitlab-ci.yml
+stages:
+  - build
+  - test
+  - package
+  - publish
+
+variables:
+  NODE_VERSION: "22"
+
+build:
+  stage: build
+  image: node:${NODE_VERSION}-alpine
+  script:
+    - npm ci
+    - npm run build
+  artifacts:
+    paths:
+      - dist/
+
+test:
+  stage: test
+  image: node:${NODE_VERSION}-alpine
+  script:
+    - npm ci
+    - npm test
+  coverage: '/Lines\s*:\s*(\d+\.?\d*)%/'
+
+package:
+  stage: package
+  image: node:${NODE_VERSION}-alpine
+  script:
+    - npm ci
+    - npm run package
+  artifacts:
+    paths:
+      - release/
+  only:
+    - tags
+
+publish:
+  stage: publish
+  image: node:${NODE_VERSION}-alpine
+  script:
+    - npm ci
+    - npm publish
+  only:
+    - tags
+  environment: production
+```
+
+### Multi-Platform (GitLab)
+
+```yaml
+# Using GitLab CI with Docker-in-Docker for multi-arch
+build-multiarch:
+  stage: package
+  image: docker:latest
+  services:
+    - docker:dind
+  script:
+    - docker buildx create --use
+    - docker buildx build --platform linux/amd64,linux/arm64 -t $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG --push .
+  only:
+    - tags
+```
+
+---
+
+## Jenkins
+
+### Jenkinsfile (Declarative Pipeline)
+
+```groovy
+// Jenkinsfile
+pipeline {
+    agent any
+    environment {
+        NODE_VERSION = '22'
+    }
+    stages {
+        stage('Build') {
+            steps {
+                sh 'npm ci'
+                sh 'npm run build'
+            }
+        }
+        stage('Test') {
+            steps {
+                sh 'npm test'
+            }
+        }
+        stage('Package') {
+            when { tag pattern: "v\\d+\\.\\d+\\.\\d+", comparator: "REGEXP" }
+            steps {
+                sh 'npm run package'
+            }
+        }
+        stage('Publish') {
+            when { tag pattern: "v\\d+\\.\\d+\\.\\d+", comparator: "REGEXP" }
+            steps {
+                withCredentials([string(credentialsId: 'npm-token', variable: 'NPM_TOKEN')]) {
+                    sh 'npm publish'
+                }
+            }
+        }
+    }
+    post {
+        always {
+            cleanWs()
+        }
+        success {
+            slackSend(channel: '#builds', message: "Build succeeded: ${env.JOB_NAME} #${env.BUILD_NUMBER}")
+        }
+        failure {
+            slackSend(channel: '#builds', message: "Build failed: ${env.JOB_NAME} #${env.BUILD_NUMBER}")
+        }
+    }
+}
+```
+
+---
+
+## Common CI/CD Patterns
+
+### Pattern: Tag-Based Release
+
+```bash
+# Developer workflow:
+git tag v1.2.3
+git push origin v1.2.3
+# CI automatically: build → test → package → publish → create release
+```
+
+### Pattern: Monorepo CI
+
+```yaml
+# Only run jobs for changed packages
+on:
+  push:
+    paths:
+      - 'packages/web/**'
+      - 'packages/shared/**'
+```
+
+### Pattern: Matrix Build
+
+```yaml
+strategy:
+  matrix:
+    os: [ubuntu-latest, macos-latest, windows-latest]
+    node: [20, 22]
+    exclude:
+      - os: macos-latest
+        node: 20  # Save macOS runner minutes
+```
+
+### Pattern: Caching
+
+```yaml
+# npm
+- uses: actions/cache@v4
+  with:
+    path: ~/.npm
+    key: npm-${{ hashFiles('package-lock.json') }}
+
+# Gradle
+- uses: actions/cache@v4
+  with:
+    path: |
+      ~/.gradle/caches
+      ~/.gradle/wrapper
+    key: gradle-${{ hashFiles('**/*.gradle*') }}
+
+# Docker layers
+cache-from: type=gha
+cache-to: type=gha,mode=max
+```
+
+---
+
+## Platform Comparison
+
+| Feature | GitHub Actions | GitLab CI | Jenkins |
+|---------|---------------|-----------|---------|
+| Hosting | GitHub Cloud | GitLab Cloud / Self-hosted | Self-hosted |
+| Free tier | 2000 min/month | 400 min/month | Unlimited (self-hosted) |
+| Config format | YAML | YAML | Groovy (Jenkinsfile) |
+| Marketplace | Large (actions) | Smaller | Huge (plugins) |
+| Matrix builds | Yes | Yes | Yes |
+| Best for | GitHub repos | GitLab repos | On-premise, complex workflows |
+
+## Common Pitfalls
+
+| Issue | Fix |
+|-------|-----|
+| Secrets not available in PRs | PRs from forks don't have secrets; use `pull_request_target` carefully |
+| Build timeout | Increase timeout; optimize build (caching, parallel jobs) |
+| macOS runner expensive | Use Linux for testing; macOS only for packaging |
+| Artifact size limit | GitHub: 500MB per artifact; use release assets for large files |
+| Tag triggers not working | Ensure tag pattern matches: `tags: ['v*']` |
+| Docker build slow | Use BuildKit caching; multi-stage builds; smaller base images |
+| Node_modules cache not working | Check `cache` option in `setup-node`; verify lockfile hash |

package/sub-skills/cloud/docker.md

@@ -0,0 +1,191 @@
+# Docker Containerization Sub-Skill
+
+Containerize any project for deployment using Docker.
+
+## When to Use
+
+- Backend service containerization
+- Frontend static resource containerization
+- Full-stack application containerization
+- Microservice architecture
+- Development environment standardization
+
+## Dockerfile Templates
+
+### Node.js Application
+
+```dockerfile
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:22-alpine
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package.json ./
+RUN apk add --no-cache tini && \
+    addgroup -S appgroup && adduser -S appuser -G appgroup && \
+    chown -R appuser:appgroup /app
+USER appuser
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:3000/health || exit 1
+ENTRYPOINT ["/sbin/tini", "--"]
+CMD ["node", "dist/server.js"]
+```
+
+### Python Application
+
+```dockerfile
+FROM python:3.13-slim AS builder
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
+
+FROM python:3.13-slim
+WORKDIR /app
+COPY --from=builder /install /usr/local
+COPY . .
+RUN groupadd -r appuser && useradd -r -g appuser appuser && \
+    chown -R appuser:appuser /app
+USER appuser
+EXPOSE 8000
+HEALTHCHECK --interval=30s --timeout=3s CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1
+CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:8000", "app:app"]
+```
+
+### Go Application
+
+```dockerfile
+FROM golang:1.23-alpine AS builder
+WORKDIR /app
+COPY go.* ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o myapp .
+
+FROM alpine:latest
+RUN apk add --no-cache ca-certificates tzdata && \
+    addgroup -S appgroup && adduser -S appuser -G appgroup
+COPY --from=builder /app/myapp /myapp
+USER appuser
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:8080/health || exit 1
+CMD ["/myapp"]
+```
+
+### Static Frontend
+
+```dockerfile
+FROM nginx:alpine
+RUN addgroup -S appgroup && adduser -S appuser -G appgroup
+COPY dist/ /usr/share/nginx/html
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+RUN chown -R appuser:appgroup /usr/share/nginx/html
+USER appuser
+EXPOSE 80
+HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:80/ || exit 1
+```
+
+## Docker Compose
+
+```yaml
+services:
+  app:
+    build: .
+    ports: ["3000:3000"]
+    environment:
+      - DATABASE_URL=postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
+    depends_on:
+      db:
+        condition: service_healthy
+    restart: unless-stopped
+  db:
+    image: postgres:16
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: ${POSTGRES_DB}
+    volumes: ["pgdata:/var/lib/postgresql/data"]
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    restart: unless-stopped
+volumes:
+  pgdata:
+```
+
+> **Security**: Never hardcode passwords in docker-compose.yml. Use `.env` file (add to `.gitignore`) or Docker secrets.
+
+> **Best practice**: Commit a `.env.example` file (without real values) to version control so other developers know which environment variables are required. The actual `.env` file must remain in `.gitignore`.
+>
+> ```text
+> # .env.example (commit this — no real values)
+> POSTGRES_USER=your_user
+> POSTGRES_PASSWORD=
+> POSTGRES_DB=your_db
+> ```
+
+## .dockerignore (Required)
+
+```text
+# .dockerignore — must be in the same directory as Dockerfile
+node_modules
+.git
+.gitignore
+.env
+.env.*
+*.md
+.dockerignore
+Dockerfile
+docker-compose*.yml
+.vscode
+.idea
+coverage
+test
+tests
+*.log
+dist
+build
+```
+
+## Image Security Scanning
+
+```bash
+# Scan for vulnerabilities before pushing
+docker scout cves myapp:latest           # Docker Scout (built-in)
+trivy image myapp:latest                 # Trivy (open-source)
+grype myapp:latest                       # Anchore Grype
+
+# Scan in CI
+docker scout cves --only-severity critical,high myapp:latest
+```
+
+## Best Practices
+
+| Practice | Description |
+|----------|-------------|
+| Multi-stage build | Reduce image size by separating build and runtime |
+| Alpine base image | Smaller images (5MB vs 100MB+ for Debian) |
+| .dockerignore | Exclude node_modules, .git, .env, tests |
+| Non-root user | Run as non-root in production (`USER appuser`) |
+| Health check | `HEALTHCHECK` instruction for container orchestration |
+| Pinned versions | Avoid `latest` tag; use specific versions (`node:22.3.1-alpine`) |
+| No secrets in image | Use env vars, Docker secrets, or mounted volumes |
+| Image scanning | Scan for CVEs before pushing (`docker scout cves`) |
+| Read-only filesystem | `--read-only` flag prevents runtime file modifications |
+| No `ADD` when `COPY` suffices | `ADD` can fetch URLs and extract archives (security risk) |
+
+## Common Pitfalls
+
+| Issue | Fix |
+|-------|-----|
+| Large image | Multi-stage build + Alpine |
+| Slow build | Leverage Docker layer caching |
+| Permission issues | Use non-root user |
+| Timezone | Set `TZ` environment variable |