opencode-skills-collection 4.0.67 → 4.0.69

package/bundled-skills/planetscale/SKILL.md

@@ -0,0 +1,297 @@
+---
+name: planetscale
+description: Operate MySQL-compatible databases on PlanetScale with branching workflows,
+  safe migrations, and production rollouts.
+category: devops
+risk: critical
+source: https://github.com/BagelHole/DevOps-Security-Agent-Skills
+source_repo: BagelHole/DevOps-Security-Agent-Skills
+source_type: community
+date_added: '2026-09-20'
+license: MIT
+license_source: https://github.com/BagelHole/DevOps-Security-Agent-Skills/blob/main/LICENSE
+compatibility: Requires the relevant OS/platform tooling and privileged access where
+  noted. Docs-only; helper scripts and templates not bundled.
+metadata:
+  author: devops-skills
+  version: '1.0'
+---
+
+# PlanetScale
+
+Use PlanetScale for serverless MySQL-compatible databases with non-blocking schema change workflows built on Vitess.
+
+## When to Use
+
+- You need a managed MySQL-compatible database with zero-downtime migrations.
+- Your team wants Git-like branching for schema development.
+- You are building a serverless or edge application that benefits from connection pooling.
+- You need horizontal sharding without managing Vitess directly.
+
+## Prerequisites
+
+- A PlanetScale account (free tier available).
+- The `pscale` CLI installed locally.
+- Node.js 18+ if using Prisma or other ORM integrations.
+
+## Install the pscale CLI
+
+```bash
+# macOS
+brew install planetscale/tap/pscale
+
+# Linux (deb)
+curl -fsSL https://github.com/planetscale/cli/releases/latest/download/pscale_linux_amd64.deb -o pscale.deb
+sudo dpkg -i pscale.deb
+
+# Verify installation
+pscale version
+
+# Authenticate
+pscale auth login
+```
+
+## Create and Manage Databases
+
+```bash
+# Create a new database
+pscale database create my-app --region us-east
+
+# List databases
+pscale database list
+
+# Show database info
+pscale database show my-app
+
+# Delete a database (destructive)
+pscale database delete my-app
+```
+
+## Branching Workflow
+
+PlanetScale branches work like Git branches for your database schema. The `main` branch is the production branch by default.
+
+```bash
+# Create a development branch from main
+pscale branch create my-app add-users-table
+
+# List all branches
+pscale branch list my-app
+
+# Open a shell on the branch to apply schema changes
+pscale shell my-app add-users-table
+```
+
+### Apply Schema Changes on a Branch
+
+```sql
+-- Inside the pscale shell on the development branch
+CREATE TABLE users (
+  id         BIGINT       NOT NULL AUTO_INCREMENT PRIMARY KEY,
+  email      VARCHAR(255) NOT NULL,
+  name       VARCHAR(255) NOT NULL,
+  created_at TIMESTAMP    DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP    DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  UNIQUE KEY idx_users_email (email)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+CREATE TABLE orders (
+  id         BIGINT    NOT NULL AUTO_INCREMENT PRIMARY KEY,
+  user_id    BIGINT    NOT NULL,
+  total      DECIMAL(10,2) NOT NULL DEFAULT 0.00,
+  status     ENUM('pending','paid','shipped','cancelled') DEFAULT 'pending',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  KEY idx_orders_user_id (user_id),
+  KEY idx_orders_status (status)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```
+
+> PlanetScale does not enforce foreign keys at the database level. Use application-level constraints or Vitess-level routing rules instead.
+
+## Deploy Requests
+
+Deploy requests are the pull-request equivalent for database schemas. They show a diff, run linting, and merge non-blocking into production.
+
+```bash
+# Create a deploy request from branch to main
+pscale deploy-request create my-app add-users-table
+
+# List open deploy requests
+pscale deploy-request list my-app
+
+# Show diff for a deploy request
+pscale deploy-request diff my-app 1
+
+# Deploy (merge) the request
+pscale deploy-request deploy my-app 1
+
+# Close without deploying
+pscale deploy-request close my-app 1
+
+# Delete the branch after successful deploy
+pscale branch delete my-app add-users-table
+```
+
+## Connection Strings and Proxying
+
+```bash
+# Create a password (connection credential) for a branch
+pscale password create my-app main production-creds
+
+# Output includes host, username, and password for the connection string:
+# mysql://USERNAME:PASSWORD@HOST/my-app?sslmode=verify_identity
+
+# Proxy a branch to localhost for local development (no password needed)
+pscale connect my-app add-users-table --port 3306
+```
+
+### Environment Variable Pattern
+
+```bash
+# .env (local development using pscale connect)
+DATABASE_URL="mysql://root@127.0.0.1:3306/my-app"
+
+# .env.production (using PlanetScale connection string)
+DATABASE_URL="mysql://USERNAME:PASSWORD@us-east.connect.psdb.cloud/my-app?sslaccept=strict"
+```
+
+## Prisma Integration
+
+```prisma
+// prisma/schema.prisma
+datasource db {
+  provider     = "mysql"
+  url          = env("DATABASE_URL")
+  relationMode = "prisma"   // required — PlanetScale does not support foreign keys
+}
+
+model User {
+  id        Int      @id @default(autoincrement())
+  email     String   @unique
+  name      String
+  orders    Order[]
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+}
+
+model Order {
+  id        Int      @id @default(autoincrement())
+  userId    Int
+  total     Decimal  @db.Decimal(10, 2)
+  status    String   @default("pending")
+  user      User     @relation(fields: [userId], references: [id])
+  createdAt DateTime @default(now())
+
+  @@index([userId])
+  @@index([status])
+}
+```
+
+```bash
+# Push schema changes to the PlanetScale branch
+npx prisma db push
+
+# Generate the Prisma client
+npx prisma generate
+```
+
+## Vitess Features and Query Insights
+
+```bash
+# Open the query insights dashboard
+pscale shell my-app main
+
+# Inside the shell, check running queries
+SHOW PROCESSLIST;
+
+# Examine query statistics (PlanetScale Insights tab in the web UI)
+# Or use the API:
+pscale api organizations/my-org/databases/my-app/branches/main/query-statistics
+```
+
+### Useful Vitess-Aware Queries
+
+```sql
+-- Check table sizes
+SELECT table_name,
+       ROUND(data_length / 1024 / 1024, 2) AS data_mb,
+       ROUND(index_length / 1024 / 1024, 2) AS index_mb,
+       table_rows
+FROM information_schema.tables
+WHERE table_schema = 'my-app'
+ORDER BY data_length DESC;
+
+-- Show index usage
+SHOW INDEX FROM users;
+
+-- Explain a query plan
+EXPLAIN SELECT * FROM orders WHERE user_id = 42 AND status = 'paid';
+```
+
+## Docker Setup for Local Development
+
+Use a plain MySQL 8 container to mirror PlanetScale locally when you are offline or want fast iteration without the CLI proxy.
+
+```yaml
+# docker-compose.yml
+version: "3.9"
+
+services:
+  mysql:
+    image: mysql:8.0
+    restart: unless-stopped
+    ports:
+      - "3306:3306"
+    environment:
+      MYSQL_ROOT_PASSWORD: rootpass
+      MYSQL_DATABASE: my-app
+      MYSQL_USER: myapp
+      MYSQL_PASSWORD: secret
+    volumes:
+      - mysql_data:/var/lib/mysql
+      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
+    command: >
+      --default-authentication-plugin=mysql_native_password
+      --character-set-server=utf8mb4
+      --collation-server=utf8mb4_unicode_ci
+
+volumes:
+  mysql_data:
+```
+
+```bash
+docker compose up -d
+mysql -h 127.0.0.1 -u myapp -psecret my-app
+```
+
+## Production Best Practices
+
+- Keep every schema change backward compatible; deploy the schema first, then the application code.
+- Use deploy request reviews as a gate; require at least one approval before merging.
+- Enable connection pooling (`@planetscale/database` driver or Prisma Data Proxy) for serverless workloads.
+- Monitor query insights weekly and add indexes for queries exceeding 100 ms.
+- Set branch promotion rules so only specific team members can deploy to `main`.
+- Use read-only regions to reduce latency for geographically distributed reads.
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+|---|---|---|
+| `Access denied` on `pscale connect` | CLI not authenticated | Run `pscale auth login` |
+| Deploy request shows "schema conflict" | Concurrent branch changes to the same table | Rebase: delete branch, recreate from current `main`, reapply changes |
+| `foreign key constraint` error | PlanetScale does not support foreign keys | Use `relationMode = "prisma"` or remove FK definitions |
+| High latency on reads | No index on queried column | Add index via a new branch and deploy request |
+| `max connections` exceeded | Connection pooling not enabled | Use `@planetscale/database` serverless driver or PgBouncer-style proxy |
+| `pscale connect` hangs | Firewall blocking outbound TLS | Allow outbound 443 to `*.psdb.cloud` |
+
+## Related Skills
+
+- mysql (`mysql`) - MySQL tuning fundamentals
+- database-backups (`database-backups`) - Recovery planning
+- postgresql (`postgresql-devsec`) - Alternative relational database
+
+## Limitations
+
+- Infrastructure commands can disrupt services: confirm target host/scope and have backups/snapshots before mutating state.
+- Docs-only import: upstream scripts and templates not bundled.
+

package/bundled-skills/platform-engineering/SKILL.md

@@ -0,0 +1,348 @@
+---
+name: platform-engineering
+description: Build internal developer platforms (IDPs) with self-service infrastructure,
+  golden paths, and developer portals using Backstage, Crossplane, and score.
+category: devops
+risk: critical
+source: https://github.com/BagelHole/DevOps-Security-Agent-Skills
+source_repo: BagelHole/DevOps-Security-Agent-Skills
+source_type: community
+date_added: '2026-09-20'
+license: MIT
+license_source: https://github.com/BagelHole/DevOps-Security-Agent-Skills/blob/main/LICENSE
+compatibility: Requires the relevant platform CLIs (kubectl, helm, terraform, git,
+  CI runners) and authorized access to the target environment. Docs-only; helper scripts
+  and templates not bundled.
+metadata:
+  author: devops-skills
+  version: '1.0'
+---
+
+# Platform Engineering
+
+Platform engineering is the discipline of building and maintaining internal developer platforms (IDPs) that enable self-service capabilities for software engineering teams. The goal is to reduce cognitive load, standardize infrastructure provisioning, and accelerate delivery while maintaining governance and security guardrails.
+
+---
+
+## 2. Backstage Setup
+
+[Backstage](https://backstage.io) is the leading open-source developer portal framework, originally created at Spotify.
+
+### Installation
+
+```bash
+# Prerequisites: Node.js 18+, yarn 1.x
+npx @backstage/create-app@latest
+
+# Follow the prompts -- name your app, e.g., "internal-platform"
+cd internal-platform
+
+# Start the development server
+yarn dev
+```
+
+### Production Docker Build
+
+```dockerfile
+# Dockerfile for Backstage production image
+FROM node:18-bookworm-slim AS build
+WORKDIR /app
+
+COPY package.json yarn.lock ./
+COPY packages/ packages/
+COPY plugins/ plugins/
+
+RUN yarn install --frozen-lockfile
+RUN yarn tsc
+RUN yarn build:backend
+
+FROM node:18-bookworm-slim
+WORKDIR /app
+
+COPY --from=build /app/packages/backend/dist/ ./
+COPY --from=build /app/node_modules/ ./node_modules/
+COPY app-config.yaml app-config.production.yaml ./
+
+ENV NODE_ENV=production
+CMD ["node", "packages/backend", "--config", "app-config.production.yaml"]
+```
+
+### Core app-config.yaml
+
+```yaml
+# app-config.yaml
+app:
+  title: Internal Developer Platform
+  baseUrl: http://localhost:3000
+
+organization:
+  name: MyOrg
+
+backend:
+  baseUrl: http://localhost:7007
+  listen:
+    port: 7007
+  database:
+    client: pg
+    connection:
+      host: ${POSTGRES_HOST}
+      port: ${POSTGRES_PORT}
+      user: ${POSTGRES_USER}
+      password: ${POSTGRES_PASSWORD}
+
+integrations:
+  github:
+    - host: github.com
+      token: ${GITHUB_TOKEN}
+
+catalog:
+  import:
+    entityFilename: catalog-info.yaml
+    pullRequestBranchName: backstage-integration
+  rules:
+    - allow: [Component, System, API, Resource, Location, Template]
+  locations:
+    - type: url
+      target: https://github.com/myorg/software-catalog/blob/main/catalog-info.yaml
+    - type: url
+      target: https://github.com/myorg/backstage-templates/blob/main/all-templates.yaml
+```
+
+---
+
+## 3. Crossplane for Self-Service Infrastructure
+
+Crossplane extends Kubernetes to provision and manage cloud infrastructure through declarative YAML.
+
+### Install Crossplane
+
+```bash
+# Add the Crossplane Helm repo
+helm repo add crossplane-stable https://charts.crossplane.io/stable
+helm repo update
+
+# Install Crossplane into its own namespace
+helm install crossplane crossplane-stable/crossplane \
+  --namespace crossplane-system \
+  --create-namespace \
+  --set args='{"--enable-composition-revisions"}'
+
+# Install the AWS provider
+kubectl apply -f - <<EOF
+apiVersion: pkg.crossplane.io/v1
+kind: Provider
+metadata:
+  name: provider-aws
+spec:
+  package: xpkg.upbound.io/upbound/provider-family-aws:v1.1.0
+EOF
+
+# Configure AWS credentials
+kubectl create secret generic aws-creds \
+  -n crossplane-system \
+  --from-file=creds=./aws-credentials.txt
+
+kubectl apply -f - <<EOF
+apiVersion: aws.upbound.io/v1beta1
+kind: ProviderConfig
+metadata:
+  name: default
+spec:
+  credentials:
+    source: Secret
+    secretRef:
+      namespace: crossplane-system
+      name: aws-creds
+      key: creds
+EOF
+```
+
+### CompositeResourceDefinition (XRD)
+
+This defines a new platform API that developers consume without knowing the underlying cloud resources.
+
+```yaml
+# xrd-application-database.yaml
+apiVersion: apiextensions.crossplane.io/v1
+kind: CompositeResourceDefinition
+metadata:
+  name: xapplicationdatabases.platform.myorg.io
+spec:
+  group: platform.myorg.io
+  names:
+    kind: XApplicationDatabase
+    plural: xapplicationdatabases
+  claimNames:
+    kind: ApplicationDatabase
+    plural: applicationdatabases
+  versions:
+    - name: v1alpha1
+      served: true
+      referenceable: true
+      schema:
+        openAPIV3Schema:
+          type: object
+          properties:
+            spec:
+              type: object
+              properties:
+                parameters:
+                  type: object
+                  properties:
+                    engine:
+                      type: string
+                      enum: ["postgres", "mysql"]
+                      default: "postgres"
+                    engineVersion:
+                      type: string
+                      default: "15"
+                    storageGB:
+                      type: integer
+                      minimum: 20
+                      maximum: 500
+                      default: 20
+                    instanceSize:
+                      type: string
+                      enum: ["small", "medium", "large"]
+                      default: "small"
+                    environment:
+                      type: string
+                      enum: ["dev", "staging", "prod"]
+                  required:
+                    - environment
+```
+
+### Composition (AWS RDS)
+
+```yaml
+# composition-aws-database.yaml
+apiVersion: apiextensions.crossplane.io/v1
+kind: Composition
+metadata:
+  name: applicationdatabase-aws
+  labels:
+    provider: aws
+spec:
+  compositeTypeRef:
+    apiVersion: platform.myorg.io/v1alpha1
+    kind: XApplicationDatabase
+  resources:
+    - name: rds-instance
+      base:
+        apiVersion: rds.aws.upbound.io/v1beta1
+        kind: Instance
+        spec:
+          forProvider:
+            region: us-east-1
+            allocatedStorage: 20
+            autoMinorVersionUpgrade: true
+            backupRetentionPeriod: 7
+            dbName: appdb
+            deletionProtection: false
+            publiclyAccessible: false
+            skipFinalSnapshot: true
+            storageEncrypted: true
+            storageType: gp3
+            vpcSecurityGroupIdSelector:
+              matchLabels:
+                platform.myorg.io/network: shared
+            dbSubnetGroupNameSelector:
+              matchLabels:
+                platform.myorg.io/network: shared
+      patches:
+        - type: FromCompositeFieldPath
+          fromFieldPath: spec.parameters.engine
+          toFieldPath: spec.forProvider.engine
+        - type: FromCompositeFieldPath
+          fromFieldPath: spec.parameters.engineVersion
+          toFieldPath: spec.forProvider.engineVersion
+        - type: FromCompositeFieldPath
+          fromFieldPath: spec.parameters.storageGB
+          toFieldPath: spec.forProvider.allocatedStorage
+        - type: CombineFromComposite
+          combine:
+            variables:
+              - fromFieldPath: spec.parameters.instanceSize
+            strategy: map
+            map:
+              small: db.t3.micro
+              medium: db.t3.medium
+              large: db.r6g.large
+          toFieldPath: spec.forProvider.instanceClass
+    - name: db-secret
+      base:
+        apiVersion: secretstores.aws.upbound.io/v1beta1
+        kind: Secret
+        spec:
+          forProvider:
+            region: us-east-1
+      patches:
+        - type: FromCompositeFieldPath
+          fromFieldPath: metadata.name
+          toFieldPath: spec.forProvider.name
+          transforms:
+            - type: string
+              string:
+                fmt: "platform/%s/db-credentials"
+```
+
+### Developer Claim (what devs actually write)
+
+```yaml
+# my-app-database.yaml
+apiVersion: platform.myorg.io/v1alpha1
+kind: ApplicationDatabase
+metadata:
+  name: orders-db
+  namespace: team-commerce
+spec:
+  parameters:
+    engine: postgres
+    engineVersion: "15"
+    storageGB: 50
+    instanceSize: medium
+    environment: staging
+```
+
+---
+
+
+## Contents
+
+- [4. Golden Paths](references/details.md)
+- [5. Service Catalog](references/details.md)
+- [6. Developer Portal -- Backstage Plugins](references/details.md)
+- [7. Score Specification](references/details.md)
+- [8. Self-Service Workflows](references/details.md)
+- [9. Platform Metrics](references/details.md)
+- [10. Governance -- Policy Enforcement](references/details.md)
+- [Summary](references/details.md)
+
+## When to Use
+
+Adopt platform engineering practices when your organization experiences:
+
+- **Cognitive overload on dev teams** -- developers spend more time on infrastructure wiring than writing business logic.
+- **Inconsistent environments** -- every team provisions infrastructure differently, causing drift and outages.
+- **Slow onboarding** -- new engineers take weeks to get a working development environment.
+- **Repeated toil** -- the same Terraform/Helm/CI boilerplate is copy-pasted across dozens of repos.
+- **Compliance bottlenecks** -- security and ops reviews gate every deployment, slowing release cadence.
+- **Scale inflection points** -- you have 5+ teams and shared infrastructure concerns (networking, observability, secrets).
+
+Platform engineering is NOT about replacing ops with a portal. It is about encoding organizational standards into reusable, self-service abstractions that dev teams consume through golden paths.
+
+---
+
+## Limitations
+
+- Guidance executes against real environments: confirm target, blast radius, and rollback plan before applying anything.
+- Never deploy to production without explicit approval. Docs-only import: upstream scripts and templates not bundled.
+
+### Example
+
+```bash
+git status && git diff --stat
+kubectl diff -f manifest.yaml
+```
+
+> Adapted from [BagelHole/DevOps-Security-Agent-Skills](https://github.com/BagelHole/DevOps-Security-Agent-Skills) (MIT); frontmatter, When to Use/Limitations, and safety boundaries added for upstream compliance. Docs-only import: helper scripts and templates not bundled.