@marcfargas/skills 0.1.0 → 0.2.1

package/google-cloud/gcloud/data.md

@@ -0,0 +1,119 @@
+# Data: Cloud SQL, BigQuery, Pub/Sub
+
+## Cloud SQL
+
+```bash
+# ⚠️ EXPENSIVE — always-on, ~$8-400+/mo depending on tier
+gcloud sql instances create my-db \
+  --database-version=POSTGRES_15 \
+  --tier=db-f1-micro \
+  --region=europe-west1
+
+# Create database
+gcloud sql databases create mydb --instance=my-db
+gcloud sql databases list --instance=my-db --format=json
+
+# Create user — NEVER put password in CLI args
+# Use --prompt-for-password or pull from Secret Manager
+gcloud sql users create myuser --instance=my-db --prompt-for-password
+
+# Or from Secret Manager
+gcloud sql users set-password myuser --instance=my-db \
+  --password="$(gcloud secrets versions access latest --secret=db-password)"
+
+# Connect directly
+gcloud sql connect my-db --user=myuser
+
+# Cloud SQL Auth Proxy (for local dev — preferred)
+cloud-sql-proxy PROJECT_ID:europe-west1:my-db
+
+# Export/Import
+gcloud sql export sql my-db gs://my-bucket/backup.sql --database=mydb
+gcloud sql import sql my-db gs://my-bucket/backup.sql --database=mydb  # ⚠️ overwrites
+
+# READ
+gcloud sql instances list --format=json
+gcloud sql instances describe my-db --format=json
+
+# ⚠️ DESTRUCTIVE
+gcloud sql instances delete my-db
+```
+
+---
+
+## BigQuery (bq)
+
+### Datasets & Tables
+
+```bash
+# Create dataset
+bq mk my_dataset
+bq ls --format=json
+
+# Create table with schema
+bq mk --table my_dataset.my_table schema.json
+
+# READ
+bq show --format=json my_dataset.my_table
+bq head my_dataset.my_table
+```
+
+### Queries
+
+```bash
+# Query (always use Standard SQL)
+bq query --use_legacy_sql=false --format=json \
+  'SELECT * FROM `project.dataset.table` LIMIT 10'
+
+# Dry run (estimate bytes scanned — cost check)
+bq query --use_legacy_sql=false --dry_run \
+  'SELECT * FROM `project.dataset.table`'
+```
+
+### Load & Export
+
+```bash
+# Load from GCS
+bq load --source_format=CSV my_dataset.my_table gs://bucket/data.csv schema.json
+bq load --autodetect --source_format=NEWLINE_DELIMITED_JSON \
+  my_dataset.my_table gs://bucket/data.jsonl
+
+# Export to GCS
+bq extract --destination_format=CSV my_dataset.my_table gs://bucket/export.csv
+```
+
+### Delete
+
+```bash
+# ⚠️ DESTRUCTIVE — drops table
+bq rm my_dataset.my_table
+
+# ⚠️ DESTRUCTIVE — drops dataset and ALL tables
+bq rm -r my_dataset
+```
+
+---
+
+## Pub/Sub
+
+```bash
+# Topics
+gcloud pubsub topics create my-topic
+gcloud pubsub topics list --format=json
+
+# Subscriptions
+gcloud pubsub subscriptions create my-sub --topic=my-topic
+gcloud pubsub subscriptions list --format=json
+
+# Publish
+gcloud pubsub topics publish my-topic --message="Hello"
+gcloud pubsub topics publish my-topic --message='{"key":"value"}' \
+  --attribute="type=event"
+
+# Pull
+gcloud pubsub subscriptions pull my-sub --auto-ack --limit=10 --format=json
+
+# ⚠️ DESTRUCTIVE
+gcloud pubsub topics delete my-topic
+gcloud pubsub subscriptions delete my-sub
+```

package/google-cloud/gcloud/iam.md

@@ -0,0 +1,137 @@
+# IAM, Projects & Secrets
+
+## Projects
+
+```bash
+gcloud projects list --format=json
+gcloud projects create PROJECT_ID --name="Display Name"
+gcloud config set project PROJECT_ID
+gcloud config get-value project
+gcloud projects describe PROJECT_ID --format=json
+
+# Link billing (required for resource creation)
+gcloud billing accounts list
+gcloud billing projects link PROJECT_ID --billing-account=ACCOUNT_ID
+```
+
+## APIs
+
+Most APIs are disabled by default. Enable before first use:
+
+```bash
+# Enable single API
+gcloud services enable compute.googleapis.com
+
+# Enable multiple at once
+gcloud services enable \
+  compute.googleapis.com \
+  container.googleapis.com \
+  run.googleapis.com \
+  cloudsql.googleapis.com \
+  secretmanager.googleapis.com \
+  cloudbuild.googleapis.com \
+  artifactregistry.googleapis.com
+
+# List enabled APIs
+gcloud services list --format=json
+
+# Check if specific API is enabled
+gcloud services list --filter="name:run.googleapis.com" --format="value(name)"
+```
+
+## IAM Roles
+
+```bash
+# View project IAM policy
+gcloud projects get-iam-policy PROJECT_ID --format=json
+
+# Grant role (WRITE — confirm with user)
+gcloud projects add-iam-policy-binding PROJECT_ID \
+  --member="user:user@example.com" \
+  --role="roles/compute.instanceAdmin.v1"
+
+# Check what roles a user has
+gcloud projects get-iam-policy PROJECT_ID \
+  --flatten="bindings[].members" \
+  --filter="bindings.members:user@example.com" \
+  --format="table(bindings.role)"
+
+# ⚠️ DESTRUCTIVE — remove role
+gcloud projects remove-iam-policy-binding PROJECT_ID \
+  --member="user:user@example.com" \
+  --role="roles/compute.instanceAdmin.v1"
+```
+
+> **Least privilege**: Use specific roles (`roles/compute.instanceAdmin.v1`),
+> never `roles/owner` or `roles/editor` for automation.
+
+## Service Accounts
+
+```bash
+# Create
+gcloud iam service-accounts create SA_NAME --display-name="Description"
+
+# List
+gcloud iam service-accounts list --format=json
+
+# Grant role to service account
+gcloud projects add-iam-policy-binding PROJECT_ID \
+  --member="serviceAccount:SA_EMAIL" \
+  --role="roles/run.admin"
+
+# Check service account permissions
+gcloud iam service-accounts get-iam-policy SA_EMAIL --format=json
+```
+
+> ⚠️ **FORBIDDEN**: Do not use `gcloud iam service-accounts keys create`.
+> Use impersonation instead (see [auth.md](auth.md)).
+> If keys are absolutely required (user explicitly confirmed), they must be
+> stored in Secret Manager, rotated within 90 days, and deleted when unused.
+
+## Secret Manager
+
+```bash
+# Create secret (pipe from stdin — no plaintext in CLI args)
+echo -n "s3cr3t" | gcloud secrets create my-secret --data-file=-
+
+# Access latest version
+gcloud secrets versions access latest --secret=my-secret
+
+# Add new version
+echo -n "new-value" | gcloud secrets versions add my-secret --data-file=-
+
+# List & describe
+gcloud secrets list --format=json
+gcloud secrets describe my-secret --format=json
+
+# Grant access to service account
+gcloud secrets add-iam-policy-binding my-secret \
+  --member="serviceAccount:SA_EMAIL" \
+  --role="roles/secretmanager.secretAccessor"
+
+# ⚠️ DESTRUCTIVE — delete secret
+gcloud secrets delete my-secret
+```
+
+## Workload Identity Federation
+
+Keyless auth for external systems (GitHub Actions, AWS, Azure):
+
+```bash
+# Create workload identity pool
+gcloud iam workload-identity-pools create github-pool \
+  --location=global \
+  --display-name="GitHub Actions Pool"
+
+# Create provider (GitHub example)
+gcloud iam workload-identity-pools providers create-oidc github-provider \
+  --location=global \
+  --workload-identity-pool=github-pool \
+  --issuer-uri="https://token.actions.githubusercontent.com" \
+  --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository"
+
+# Allow SA impersonation from GitHub
+gcloud iam service-accounts add-iam-policy-binding SA_EMAIL \
+  --role="roles/iam.workloadIdentityUser" \
+  --member="principalSet://iam.googleapis.com/projects/PROJECT_NUM/locations/global/workloadIdentityPools/github-pool/attribute.repository/ORG/REPO"
+```

package/google-cloud/gcloud/serverless.md

@@ -0,0 +1,169 @@
+# Serverless: Cloud Run, Functions, App Engine, Scheduler, Tasks
+
+## Cloud Run (Services)
+
+```bash
+# WRITE — deploy from container image
+gcloud run deploy my-service \
+  --image=europe-west1-docker.pkg.dev/PROJECT_ID/my-repo/my-image:tag \
+  --region=europe-west1 \
+  --set-env-vars="KEY=value"
+
+# Deploy from source (buildpacks — no Dockerfile needed)
+gcloud run deploy my-service --source=. --region=europe-west1
+
+# READ
+gcloud run services list --format=json
+gcloud run services describe my-service --region=europe-west1 --format=json
+gcloud run services logs read my-service --region=europe-west1
+
+# WRITE — update
+gcloud run services update my-service --region=europe-west1 --memory=512Mi --cpu=1
+
+# Traffic splitting
+gcloud run services update-traffic my-service \
+  --to-revisions=my-service-v1=50,my-service-v2=50
+
+# ⚠️ SECURITY — exposes to public internet
+gcloud run deploy my-service --allow-unauthenticated ...
+
+# ⚠️ DESTRUCTIVE
+gcloud run services delete my-service --region=europe-west1
+```
+
+## Cloud Run (Jobs — batch workloads)
+
+```bash
+# WRITE — create job
+gcloud run jobs create my-job \
+  --image=europe-west1-docker.pkg.dev/PROJECT_ID/my-repo/my-image:tag \
+  --region=europe-west1 \
+  --tasks=10 --max-retries=3
+
+# Execute
+gcloud run jobs execute my-job --region=europe-west1
+
+# READ
+gcloud run jobs list --format=json
+gcloud run jobs describe my-job --region=europe-west1 --format=json
+
+# ⚠️ DESTRUCTIVE
+gcloud run jobs delete my-job --region=europe-west1
+```
+
+## Cloud Functions (Gen 2)
+
+```bash
+# WRITE — deploy HTTP function
+gcloud functions deploy my-func \
+  --gen2 \
+  --runtime=nodejs20 \
+  --region=europe-west1 \
+  --trigger-http \
+  --entry-point=handler \
+  --source=.
+
+# Event-triggered (Pub/Sub)
+gcloud functions deploy my-func \
+  --gen2 \
+  --runtime=python312 \
+  --region=europe-west1 \
+  --trigger-topic=my-topic
+
+# ⚠️ SECURITY — exposes to public internet
+gcloud functions deploy my-func --allow-unauthenticated ...
+
+# READ
+gcloud functions list --format=json
+gcloud functions describe my-func --region=europe-west1 --format=json
+gcloud functions logs read my-func --region=europe-west1
+
+# ⚠️ DESTRUCTIVE
+gcloud functions delete my-func --region=europe-west1
+```
+
+## App Engine
+
+```bash
+gcloud app deploy app.yaml
+gcloud app browse
+gcloud app logs tail
+gcloud app versions list --format=json
+
+# ⚠️ DESTRUCTIVE
+gcloud app versions delete VERSION_ID
+
+# Traffic splitting
+gcloud app services set-traffic SERVICE --splits v1=50,v2=50
+```
+
+## Cloud Scheduler
+
+```bash
+# WRITE — create cron job
+gcloud scheduler jobs create http my-job \
+  --schedule="0 9 * * 1" \
+  --uri="https://my-service.run.app/task" \
+  --http-method=POST \
+  --location=europe-west1 \
+  --oidc-service-account-email=SA_EMAIL
+
+# Pub/Sub trigger
+gcloud scheduler jobs create pubsub my-job \
+  --schedule="*/5 * * * *" \
+  --topic=my-topic \
+  --message-body='{"action":"process"}' \
+  --location=europe-west1
+
+# READ
+gcloud scheduler jobs list --location=europe-west1 --format=json
+
+# Manual trigger
+gcloud scheduler jobs run my-job --location=europe-west1
+
+# ⚠️ DESTRUCTIVE
+gcloud scheduler jobs delete my-job --location=europe-west1
+```
+
+## Cloud Tasks
+
+```bash
+# WRITE — create queue
+gcloud tasks queues create my-queue --location=europe-west1
+
+# Create HTTP task
+gcloud tasks create-http-task \
+  --queue=my-queue \
+  --url="https://my-service.run.app/process" \
+  --http-method=POST \
+  --location=europe-west1
+
+# READ
+gcloud tasks queues list --location=europe-west1 --format=json
+
+# ⚠️ DESTRUCTIVE
+gcloud tasks queues delete my-queue --location=europe-west1
+```
+
+## GKE (Kubernetes Engine)
+
+```bash
+# ⚠️ EXPENSIVE — ~$70+/month for 3-node e2-medium cluster
+gcloud container clusters create my-cluster \
+  --zone=europe-west1-b \
+  --num-nodes=3 \
+  --machine-type=e2-medium \
+  --enable-autoscaling --min-nodes=1 --max-nodes=5
+
+# Get kubectl credentials
+gcloud container clusters get-credentials my-cluster --zone=europe-west1-b
+
+# READ
+gcloud container clusters list --format=json
+
+# WRITE — resize
+gcloud container clusters resize my-cluster --num-nodes=5 --zone=europe-west1-b
+
+# ⚠️ DESTRUCTIVE
+gcloud container clusters delete my-cluster --zone=europe-west1-b
+```

package/google-cloud/gcloud/storage.md

@@ -0,0 +1,122 @@
+# Cloud Storage & Artifact Registry
+
+## Cloud Storage
+
+> **Note**: `gsutil` is being replaced by `gcloud storage`. Both work today.
+> New scripts should prefer `gcloud storage`. Examples show both where relevant.
+
+### Buckets
+
+```bash
+# Create
+gcloud storage buckets create gs://my-bucket --location=europe-west1
+
+# List
+gcloud storage ls
+gcloud storage buckets list --format=json
+
+# ⚠️ DESTRUCTIVE — remove bucket (must be empty, or use --recursive)
+gcloud storage rm --recursive gs://my-bucket/
+```
+
+### Upload & Download
+
+```bash
+# Upload
+gcloud storage cp local.txt gs://my-bucket/
+gcloud storage cp -r ./dir gs://my-bucket/dir/    # recursive
+
+# Download
+gcloud storage cp gs://my-bucket/file.txt ./
+gcloud storage cp -r gs://my-bucket/dir/ ./local/  # recursive
+
+# Move/rename
+gcloud storage mv gs://my-bucket/old.txt gs://my-bucket/new.txt
+```
+
+### Sync
+
+```bash
+# Sync local → GCS
+gcloud storage rsync ./local-dir gs://my-bucket/remote-dir --recursive
+
+# Sync GCS → local
+gcloud storage rsync gs://my-bucket/dir ./local --recursive
+
+# ⚠️ DESTRUCTIVE: --delete-unmatched-destination-objects removes files at
+# destination not present in source. Always confirm with user.
+gcloud storage rsync ./local gs://my-bucket/dir --recursive --delete-unmatched-destination-objects
+```
+
+### List & Info
+
+```bash
+gcloud storage ls gs://my-bucket/
+gcloud storage ls -l gs://my-bucket/            # sizes
+gcloud storage du -s gs://my-bucket              # total size
+gcloud storage cat gs://my-bucket/file.txt       # print contents
+```
+
+### Permissions
+
+```bash
+# Grant read access
+gcloud storage buckets add-iam-policy-binding gs://my-bucket \
+  --member="user:user@example.com" \
+  --role="roles/storage.objectViewer"
+
+# ⚠️ SECURITY — make public
+gcloud storage buckets add-iam-policy-binding gs://my-bucket \
+  --member="allUsers" \
+  --role="roles/storage.objectViewer"
+```
+
+### Delete
+
+```bash
+# ⚠️ DESTRUCTIVE — delete objects
+gcloud storage rm gs://my-bucket/file.txt
+gcloud storage rm -r gs://my-bucket/dir/     # recursive
+gcloud storage rm -r gs://my-bucket/         # entire bucket contents + bucket
+```
+
+### gsutil equivalents (legacy)
+
+| `gcloud storage` | `gsutil` (legacy) |
+|-------------------|-------------------|
+| `gcloud storage cp` | `gsutil cp` |
+| `gcloud storage ls` | `gsutil ls` |
+| `gcloud storage rm` | `gsutil rm` |
+| `gcloud storage rsync` | `gsutil rsync` |
+| `gcloud storage mv` | `gsutil mv` |
+| `gcloud storage cat` | `gsutil cat` |
+| `gcloud storage buckets create` | `gsutil mb` |
+
+---
+
+## Artifact Registry
+
+Preferred over Container Registry for Docker images, npm packages, Python packages, etc.
+
+```bash
+# Create Docker repository
+gcloud artifacts repositories create my-repo \
+  --repository-format=docker \
+  --location=europe-west1 \
+  --description="Docker images"
+
+# Configure Docker auth
+gcloud auth configure-docker europe-west1-docker.pkg.dev
+
+# Tag and push
+docker tag my-image europe-west1-docker.pkg.dev/PROJECT_ID/my-repo/my-image:tag
+docker push europe-west1-docker.pkg.dev/PROJECT_ID/my-repo/my-image:tag
+
+# READ
+gcloud artifacts repositories list --format=json
+gcloud artifacts docker images list europe-west1-docker.pkg.dev/PROJECT_ID/my-repo --format=json
+
+# ⚠️ DESTRUCTIVE
+gcloud artifacts docker images delete europe-west1-docker.pkg.dev/PROJECT_ID/my-repo/my-image:tag
+gcloud artifacts repositories delete my-repo --location=europe-west1
+```

package/package.json

@@ -1,13 +1,46 @@
 {
   "name": "@marcfargas/skills",
-  "version": "0.1.0",
-  "description": "Pi agent skills by marcfargas",
+  "version": "0.2.1",
+  "description": "Reusable AI agent skills for pi, Claude Code, Cursor, and any Agent Skills compatible agent",
   "license": "MIT",
-  "main": "index.js",
-  "keywords": ["pi", "agent", "skills"],
+  "author": "Marc Fargas <marc@marcfargas.com>",
   "repository": {
     "type": "git",
     "url": "https://github.com/marcfargas/skills"
   },
-  "author": "Marc Fargas <marc@marcfargas.com>"
+  "keywords": [
+    "pi-package",
+    "agent-skills",
+    "ai-agent",
+    "skills",
+    "gcloud",
+    "pre-release",
+    "vhs",
+    "web-search"
+  ],
+  "pi": {
+    "skills": [
+      "google-cloud",
+      "release",
+      "search",
+      "terminal"
+    ]
+  },
+  "scripts": {
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "changeset publish"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.5.2",
+    "@changesets/cli": "^2.29.8"
+  },
+  "files": [
+    "google-cloud/",
+    "release/",
+    "search/",
+    "terminal/",
+    "README.md",
+    "LICENSE"
+  ]
 }