@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/cicd/github-flow/scripts/persist-conventions.mjs

@@ -0,0 +1,49 @@
+// persist-conventions — write the `## CI conventions` and `## Delivery` sections
+// of a repo's CONTRIBUTING.md (../SKILL.md, Persist to CONTRIBUTING.md). Run only
+// when the user asks; previews unless --write. Without --flow, writes CI conventions only.
+//
+//   node persist-conventions.mjs [--repo-root <dir>] [--write]
+//     [--flow direct|pull-request|merge-queue] [--done merged|committed] [--merge-method squash|merge|rebase]
+//     [--delivery-only]
+import fs from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { renderDelivery, validateDelivery } from './flow-core.mjs'
+import { runCli } from './persist-conventions-core.mjs'
+
+const CI = {
+  id: 'ci',
+  owner: 'github-flow',
+  title: 'CI conventions',
+  body: fs.readFileSync(fileURLToPath(new URL('../references/ci-conventions.md', import.meta.url)), 'utf8'),
+}
+
+const DELIVERY_FLAGS = { '--flow': 'flow', '--done': 'done', '--merge-method': 'mergeMethod' }
+const rest = []
+const delivery = {}
+let deliveryOnly = false
+const argv = process.argv.slice(2)
+for (let i = 0; i < argv.length; i++) {
+  const key = DELIVERY_FLAGS[argv[i]]
+  if (key && argv[i + 1]) delivery[key] = argv[++i]
+  else if (argv[i] === '--delivery-only') deliveryOnly = true
+  else rest.push(argv[i])
+}
+if (deliveryOnly && !delivery.flow) {
+  console.log('persist-conventions: --delivery-only needs --flow')
+  process.exit(2)
+}
+
+if (Object.keys(delivery).length) {
+  const errors = validateDelivery(delivery)
+  if (errors.length) {
+    for (const e of errors) console.log(`persist-conventions: ${e}`)
+    process.exit(2)
+  }
+}
+let code = deliveryOnly ? 0 : runCli(rest, CI)
+if (code === 0 && delivery.flow) {
+  code = runCli(rest, { id: 'delivery', owner: 'github-flow', title: 'Delivery', body: renderDelivery(delivery) })
+} else if (code === 0) {
+  console.log('persist-conventions: Delivery: skipped; pass --flow to write it')
+}
+process.exitCode = code

package/skills/cicd/github-flow/scripts/persist-conventions.test.mjs

@@ -0,0 +1,108 @@
+// Tests for github-flow's persist-conventions: the real CLI against real files in a temp repo.
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { spawnSync } from 'node:child_process'
+import { existsSync, lstatSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { parseDelivery } from './flow-core.mjs'
+
+const CLI = fileURLToPath(new URL('./persist-conventions.mjs', import.meta.url))
+
+function withRepo(fn) {
+  const dir = mkdtempSync(join(tmpdir(), 'github-flow-persist-'))
+  try {
+    return fn(dir, (name) => readFileSync(join(dir, name), 'utf8'))
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+const run = (dir, ...args) => spawnSync(process.execPath, [CLI, '--repo-root', dir, ...args], { encoding: 'utf8' })
+
+test('without --write it previews and writes nothing', () => {
+  withRepo((dir) => {
+    const res = run(dir, '--flow', 'direct')
+    assert.equal(res.status, 0)
+    assert.match(res.stdout, /CI conventions: preview only/)
+    assert.match(res.stdout, /Delivery: preview only/)
+    assert.equal(existsSync(join(dir, 'CONTRIBUTING.md')), false)
+  })
+})
+
+test('--write with --flow writes both sections, and the declaration reads back', () => {
+  withRepo((dir, read) => {
+    assert.equal(run(dir, '--flow', 'pull-request', '--merge-method', 'merge', '--write').status, 0)
+    const text = read('CONTRIBUTING.md')
+    assert.deepEqual(text.match(/^## .+$/gm), ['## CI conventions', '## Delivery'])
+    assert.deepEqual(parseDelivery(text), { flow: 'pull-request', done: 'merged', mergeMethod: 'merge' })
+    assert.match(read('AGENTS.md'), /\(CONTRIBUTING\.md\)/)
+  })
+})
+
+test('a re-run with a new flow replaces only the Delivery block', () => {
+  withRepo((dir, read) => {
+    run(dir, '--flow', 'direct', '--write')
+    const ci = read('CONTRIBUTING.md').split('## Delivery')[0]
+    assert.equal(run(dir, '--flow', 'merge-queue', '--done', 'committed', '--write').status, 0)
+    const text = read('CONTRIBUTING.md')
+    assert.equal(text.split('## Delivery')[0], ci)
+    assert.equal(text.match(/^## Delivery$/gm).length, 1)
+    assert.deepEqual(parseDelivery(text), { flow: 'merge-queue', done: 'committed', mergeMethod: 'squash' })
+  })
+})
+
+test('without --flow it writes CI conventions only and says Delivery was skipped', () => {
+  withRepo((dir, read) => {
+    const res = run(dir, '--write')
+    assert.equal(res.status, 0)
+    assert.match(res.stdout, /Delivery: skipped/)
+    assert.deepEqual(read('CONTRIBUTING.md').match(/^## .+$/gm), ['## CI conventions'])
+  })
+})
+
+test('an invalid delivery value fails with exit 2 and writes nothing', () => {
+  withRepo((dir) => {
+    for (const args of [['--flow', 'gitflow'], ['--done', 'merged'], ['--flow', 'direct', '--merge-method', 'ff']]) {
+      assert.equal(run(dir, ...args, '--write').status, 2, args.join(' '))
+    }
+    assert.equal(existsSync(join(dir, 'CONTRIBUTING.md')), false)
+  })
+})
+
+test('--delivery-only writes the Delivery section without CI conventions', () => {
+  withRepo((dir, read) => {
+    assert.equal(run(dir, '--flow', 'direct', '--delivery-only', '--write').status, 0)
+    assert.deepEqual(read('CONTRIBUTING.md').match(/^## .+$/gm), ['## Delivery'])
+    assert.equal(run(dir, '--delivery-only', '--write').status, 2)
+  })
+})
+
+test('CLAUDE.md reaches the conventions: created as a symlink to AGENTS.md, appended when silent, kept otherwise', () => {
+  withRepo((dir, read) => {
+    assert.match(run(dir, '--flow', 'direct').stdout, /CLAUDE\.md: would link/)
+    assert.equal(existsSync(join(dir, 'CLAUDE.md')), false)
+    assert.match(run(dir, '--flow', 'direct', '--write').stdout, /CLAUDE\.md: linked to AGENTS\.md/)
+    assert.ok(lstatSync(join(dir, 'CLAUDE.md')).isSymbolicLink())
+    assert.equal(read('CLAUDE.md'), read('AGENTS.md'))
+  })
+  withRepo((dir, read) => {
+    writeFileSync(join(dir, 'CLAUDE.md'), '# Claude\n\nUse pnpm.\n')
+    run(dir, '--flow', 'direct', '--write')
+    assert.ok(read('CLAUDE.md').startsWith('# Claude\n\nUse pnpm.\n\n## Contributing'))
+    assert.match(read('CLAUDE.md'), /\[CONTRIBUTING\.md\]\(CONTRIBUTING\.md\)/)
+  })
+  withRepo((dir, read) => {
+    writeFileSync(join(dir, 'CLAUDE.md'), 'See AGENTS.md.\n')
+    assert.match(run(dir, '--flow', 'direct', '--write').stdout, /CLAUDE\.md: unchanged/)
+    assert.equal(read('CLAUDE.md'), 'See AGENTS.md.\n')
+  })
+  withRepo((dir) => {
+    writeFileSync(join(dir, 'AGENTS.md'), '# Agents\n')
+    symlinkSync('AGENTS.md', join(dir, 'CLAUDE.md'))
+    assert.match(run(dir, '--flow', 'direct', '--write').stdout, /CLAUDE\.md: unchanged/)
+    assert.ok(lstatSync(join(dir, 'CLAUDE.md')).isSymbolicLink())
+  })
+})

package/skills/cicd/google-cloud/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

package/skills/cicd/google-cloud/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: google-cloud
+description: >
+  GCP operations covering IAM, IAP, VPC, Secret Manager, Cloud Storage, and
+  project management. Use when configuring GCP resources, managing service
+  accounts, setting up IAP access, configuring VPC networks, managing secrets,
+  or debugging cloud infrastructure.
+release-version: 0.36.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# Google Cloud Platform (GCP) Skill
+
+Reference hub for GCP operations. Use `$PROJECT_ID`, `$REGION`, and
+`$PROJECT_NUMBER` environment variables throughout — set them for your project.
+
+## Quick Commands
+
+```bash
+# Set default project
+gcloud config set project $PROJECT_ID
+
+# Set default region
+gcloud config set compute/region $REGION
+
+# List enabled APIs
+gcloud services list --enabled --project=$PROJECT_ID
+
+# Describe project
+gcloud projects describe $PROJECT_ID
+```
+
+## Topic Index
+
+Load the relevant reference file based on the task:
+
+| Task | Reference | When to load |
+|------|-----------|--------------|
+| Service accounts, roles, IAP | [references/iam.md](references/iam.md) | Configuring IAM, creating service accounts, granting roles, setting up IAP |
+| VPC, subnets, firewall rules | [references/vpc.md](references/vpc.md) | Setting up VPC networks, subnets, firewall rules, or debugging connectivity |
+| Secret Manager | [references/secrets.md](references/secrets.md) | Creating, accessing, or granting access to secrets |
+| Cloud Storage (GCS) | [references/gcs.md](references/gcs.md) | Managing buckets, objects, lifecycle policies, or GCS IAM |
+| Project metadata, quotas | [references/project.md](references/project.md) | Checking project config, quotas, billing, or API enablement |
+
+## Scripts
+
+Reusable shell scripts in `scripts/`:
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/create-sa.sh` | Create a service account with roles |
+| `scripts/gcp-config.sh` | Set up gcloud default config |
+| `scripts/grant-iap.sh` | Grant IAP access to a user or service account |
+| `scripts/setup-secrets.sh` | Create and populate secrets in Secret Manager |
+
+## Common Patterns
+
+### Service Account Token Minting
+
+```bash
+# Mint ID token for service account
+gcloud iam service-accounts get-openid-token-identity \
+  $SA_EMAIL \
+  --audiences=$AUDIENCE
+
+# Sign JWT with service account
+gcloud iam service-accounts sign-jwt /tmp/claims.json /tmp/signed.jwt \
+  --iam-account=$SA_EMAIL
+```
+
+### VPC Network Lookup
+
+```bash
+# List networks
+gcloud compute networks list
+
+# List subnets in region
+gcloud compute networks subnets list --region=$REGION
+
+# Describe specific subnet
+gcloud compute networks subnets describe $SUBNET --region=$REGION
+```
+
+### Secret Access
+
+```bash
+# List secrets
+gcloud secrets list --project=$PROJECT_ID
+
+# Access latest version
+gcloud secrets versions access latest --secret=$SECRET_NAME
+
+# Grant access to service account
+gcloud secrets add-iam-policy-binding $SECRET \
+  --member="serviceAccount:$SA_EMAIL" \
+  --role="roles/secretmanager.secretAccessor"
+```
+
+### GCS Operations
+
+```bash
+# List buckets
+gcloud storage buckets list --project=$PROJECT_ID
+
+# Upload / download / copy
+gcloud storage cp file.txt gs://$BUCKET_NAME/
+gcloud storage cp gs://$BUCKET_NAME/file.txt ./
+gcloud storage cp gs://$BUCKET_A/file.txt gs://$BUCKET_B/
+
+# Set IAM on bucket
+gcloud storage buckets add-iam-policy-binding gs://$BUCKET_NAME \
+  --member="serviceAccount:$SA_EMAIL" \
+  --role="roles/storage.objectViewer"
+```
+
+## Related Skills
+
+- [cloud-build](../cloud-build/SKILL.md) — Cloud Build → Cloud Run deployments
+- [cloud-deploy](../cloud-deploy/SKILL.md) — Cloud Deploy + Skaffold pipelines
+- [cloud-debug](../cloud-debug/SKILL.md) — Debugging Cloud Build/Deploy failures