codebyplan 1.5.0 → 1.8.0

package/templates/skills/cbp-ship-configure/reference/railway-backend.md

@@ -0,0 +1,199 @@
+# Configure: railway-backend
+
+Walkthrough for first-time Railway backend setup.
+
+Railway is the standard backend platform for the CBP family. This walkthrough covers the typical pattern: NestJS / Node service with optional Postgres / Redis Railway add-ons.
+
+## Prerequisites
+
+- Railway account (free trial; pay-as-you-go after $5 credit) — https://railway.app
+- Backend service code with a `Dockerfile` OR `package.json` with a `start` script
+- Health endpoint in your service code (e.g., `/health` returning 200) — recommended
+
+## Probe
+
+```bash
+which railway || { echo "Install: brew install railway OR npm i -g @railway/cli"; exit 1; }
+railway --version
+railway whoami || { echo "Run: railway login"; exit 1; }
+```
+
+## Setup walkthrough
+
+### Step 1/8: Create or pick a Railway project
+
+```bash
+cd "$BACKEND_PATH"
+railway init
+```
+
+Choose:
+- **New project** — name it after the repo
+- **Existing project** — pick from list
+
+This creates `.railway/config.json` linking the local dir to the Railway project.
+
+### Step 2/8: Add a service (if new project)
+
+```bash
+railway add
+```
+
+Pick:
+- **Service** — empty service for your code (the typical case)
+- **Database** — Postgres / Redis / MySQL add-on (only if you don't use Supabase)
+
+For CBP repos using Supabase, you typically only need a service (no Railway DB add-on).
+
+### Step 3/8: Link the GH repo (auto-deploy mode)
+
+```bash
+railway service connect
+# Pick GitHub → authorize → choose repo → choose branch
+```
+
+Set the deploy branch to your PRODUCTION branch (per `.codebyplan/git.json` `branch_config.production`):
+
+```
+Settings → Source → Branch: main
+Settings → Source → Path: apps/backend (if monorepo)
+```
+
+If you don't want auto-deploy (e.g., to ship deliberately via `railway up`), skip this step.
+
+### Step 4/8: Configure build mode
+
+Railway supports two build modes — pick based on your service:
+
+#### Dockerfile (recommended for NestJS)
+
+If `apps/backend/Dockerfile` exists, Railway uses it automatically. Verify:
+
+```
+Settings → Source → Builder: Dockerfile
+Settings → Source → Dockerfile Path: apps/backend/Dockerfile
+```
+
+#### Nixpacks (auto-detect)
+
+If no Dockerfile, Railway auto-detects via Nixpacks. For Node:
+
+```
+Settings → Source → Builder: Nixpacks
+```
+
+Set the start command if non-standard:
+
+```
+Settings → Deploy → Start Command: pnpm start
+```
+
+### Step 5/8: Set environment variables
+
+```bash
+# Read from .env.example for the keys
+KEYS=$(grep -E '^[A-Z_]+=' "$BACKEND_PATH/.env.example" | cut -d= -f1)
+for KEY in $KEYS; do
+  echo "Set $KEY:"
+  echo "  railway variables --set $KEY=<value> --service <service-name>"
+done
+```
+
+Set each via CLI or Railway dashboard. Railway auto-injects `PORT` — your service must bind to `process.env.PORT`.
+
+For Supabase integration, set:
+
+```bash
+railway variables --set SUPABASE_URL=https://...
+railway variables --set SUPABASE_SERVICE_ROLE_KEY=...
+railway variables --set DATABASE_URL=postgresql://...   # use Supabase pooler URL for Railway
+```
+
+### Step 6/8: Add a health endpoint (if missing)
+
+If your service doesn't have a `/health` endpoint, add one:
+
+```typescript
+// NestJS example
+@Get('/health')
+health() { return { status: 'ok', uptime: process.uptime() }; }
+```
+
+Configure Railway to use it:
+
+```
+Settings → Deploy → Healthcheck Path: /health
+Settings → Deploy → Healthcheck Timeout: 30s
+```
+
+Without a health endpoint, Railway considers any 2xx on `/` as healthy — fragile.
+
+### Step 7/8: Custom domain (optional)
+
+If you have a domain:
+
+```bash
+railway domain
+# Pick: Custom domain → enter domain
+# Update DNS: CNAME <your-domain> → <railway-domain>
+```
+
+### Step 8/8: Persist + verify
+
+```json
+{
+  "surfaces": {
+    "railway-backend": {
+      "configured_at": "<now>",
+      "platform": "railway",
+      "app_path": "apps/backend",
+      "project_id": "<from .railway/config.json>",
+      "service_id": "<from railway service --json>",
+      "environment_id": "<usually 'production'>",
+      "auto_deploy": true,
+      "production_branch": "main",
+      "url": "https://your-app.railway.app"
+    }
+  }
+}
+```
+
+Verify:
+
+```bash
+PROJECT_ID=$(jq -r '.surfaces."railway-backend".project_id' .codebyplan/shipment.json)
+railway status --json | jq
+# Expect: project + service info matching saved IDs
+```
+
+Test deploy:
+
+```bash
+railway up --detach
+# Wait, then verify URL responds
+URL=$(jq -r '.surfaces."railway-backend".url' .codebyplan/shipment.json)
+curl -sI "$URL/health" | head -1
+```
+
+## Done
+
+Surface is ready. `/cbp-ship` will deploy the backend at checkpoint end.
+
+## Common setup issues
+
+| Symptom | Fix |
+|---|---|
+| Build fails "no such file or directory: apps/backend/Dockerfile" | Set `Dockerfile Path` correctly in Railway settings; or move Dockerfile |
+| Service starts but health check fails | Healthcheck path wrong, or service is binding to hardcoded port instead of `$PORT` |
+| GH webhook doesn't fire on push | Disconnect+reconnect Source in Railway dashboard |
+| `railway variables` says "no service" | Pass `--service <name>`, or `cd` into the linked dir |
+| Deploy succeeds, app crashes immediately | Most common: missing env var; check `railway logs` |
+
+## Switching from another platform
+
+If migrating from Vercel functions / Render / Fly:
+
+1. Configure Railway as above
+2. Update DNS to point at Railway domain
+3. Add the old platform's URL to a redirect path during transition
+4. Once Railway is verified healthy, decommission the old platform

package/templates/skills/cbp-ship-configure/reference/supabase.md

@@ -0,0 +1,200 @@
+# Configure: supabase
+
+Walkthrough for first-time Supabase migration push setup.
+
+## Prerequisites
+
+- Supabase account (free tier OK for starter projects) — https://supabase.com
+- Supabase project already created in the dashboard
+- For monorepo: decide migration directory (`supabase/migrations/` at repo root, or per-app)
+
+## Probe
+
+```bash
+which supabase || { echo "Install: brew install supabase/tap/supabase"; exit 1; }
+supabase --version
+supabase projects list 2>&1 | head -3 || { echo "Run: supabase login"; exit 1; }
+```
+
+## Setup walkthrough
+
+### Step 1/7: Initialize Supabase locally (if not already)
+
+```bash
+test -d supabase || supabase init
+```
+
+Creates `supabase/config.toml`, `supabase/migrations/`, `supabase/functions/`.
+
+### Step 2/7: Link to remote project
+
+```bash
+supabase login
+# Open browser, authorize CLI
+
+supabase projects list
+# Pick your project ref (8-char string)
+
+supabase link --project-ref <your-project-ref>
+```
+
+This sets up `supabase/config.toml` with the project ref.
+
+### Step 3/7: Pull existing schema as baseline (if remote has data)
+
+If the remote Supabase project already has tables/data (created via dashboard), generate a baseline migration so local and remote agree:
+
+```bash
+supabase db dump --data-only=false --schema public,auth -f supabase/migrations/00000000000000_baseline.sql
+```
+
+Stage + commit this. Future migrations build on top of the baseline.
+
+If remote is empty (fresh project), skip this step — your migrations are the schema.
+
+### Step 4/7: Configure exposed schemas
+
+In `supabase/config.toml`:
+
+```toml
+[api]
+enabled = true
+port = 54321
+schemas = ["public", "graphql_public"]   # add custom schemas here
+extra_search_path = ["public", "extensions"]
+max_rows = 1000
+
+[db]
+port = 54322
+shadow_port = 54320
+major_version = 15
+
+[storage]
+enabled = true
+file_size_limit = "50MiB"
+```
+
+### Step 5/7: Configure types path (if using TypeScript)
+
+If your codebase imports types from `@supabase/supabase-js`, generate the types file:
+
+```bash
+supabase gen types typescript --project-id <ref> > packages/supabase/types.ts
+# OR for monorepo with web app:
+supabase gen types typescript --project-id <ref> > apps/web/types/database.types.ts
+```
+
+Decide where types live and persist that path.
+
+### Step 6/7: Optional — auto-regenerate types on migration push
+
+`/cbp-ship` can auto-regen types after migration push if the path is configured. Set up:
+
+```json
+{
+  "surfaces": {
+    "supabase": {
+      "configured_at": "<now>",
+      "project_ref": "<ref>",
+      "types_path": "packages/supabase/types.ts",
+      "auto_regenerate_types": true,
+      "exposed_schemas": ["public", "graphql_public"],
+      "last_shipped_migration_version": ""
+    }
+  }
+}
+```
+
+When `auto_regenerate_types: true`, the surface deploy step regenerates types after a successful push and surfaces the diff. The user commits the types diff before completing the checkpoint.
+
+### Step 7/7: Verify
+
+```bash
+supabase migration list --linked
+# Should show all local migrations + remote application status
+
+supabase db diff --use-migra
+# Should show NO diff (local migrations match remote)
+```
+
+If `db diff` shows differences, you have drift — resolve before first shipment:
+
+```bash
+# Capture remote drift into a migration:
+supabase db diff --use-migra -f resolve_drift
+# Review, edit, commit
+```
+
+## Done
+
+Surface is ready. `/cbp-ship` will offer to push pending migrations at checkpoint end.
+
+## Common setup issues
+
+| Symptom | Fix |
+|---|---|
+| `supabase link` fails "project not found" | Wrong ref; copy from dashboard URL `https://supabase.com/dashboard/project/<REF>` |
+| `db dump` is huge | Schema-only is fine; `--data-only=false` gets just schema |
+| Types regen output is empty | Project has no exposed schemas; check `config.toml` `api.schemas` |
+| Migration push fails on RLS policy | Migration references a role/table that doesn't exist yet; fix migration order |
+| `pnpm install` fails after type regen | Types file has invalid TS syntax (rare CLI bug); regenerate, or hand-fix the offending block |
+
+## Per-environment shipment (future)
+
+Currently this surface only ships to the `linked` project (production). Multi-environment shipment (preview / staging Supabase projects) is planned — for now, use Supabase branches in the dashboard for dev/preview.
+
+## Supabase Branching Setup
+
+After standard configure completes, `/cbp-ship-configure` checks for the GitHub branching
+integration and delegates to `/cbp-supabase-setup` when unset.
+
+### Dashboard checklist (abbreviated)
+
+1. **Project Settings → Integrations → GitHub** — Authorize GitHub, select repo,
+   set directory `./supabase`, enable Automatic branching + Supabase changes only +
+   Deploy to production.
+2. **GitHub → repo Settings → Branches** — add required-status-check rule for `main`
+   (and for `branch_config.integration` when different from `main`); select
+   **Supabase Preview** as the required check.
+
+Full walkthrough: `cbp-supabase-setup/reference/branching-setup.md`.
+
+### Persistent branch (`[remotes.<name>]` in `supabase/config.toml`)
+
+Only needed when `branch_config.integration` is set and differs from `main`.
+
+```toml
+[remotes.development]
+project_id = "xyzwabcd"   # 8-char ref from `supabase --experimental branches list`
+
+# Optional seed on branch reset (default OFF):
+# [remotes.development.db.seed]
+# enabled = true
+# sql_paths = ["./seed.sql"]
+```
+
+Replace `development` and `xyzwabcd` with the actual integration branch name and project
+ref for this repo (confirmed in `.codebyplan.json` `branch_config.integration`).
+
+### Idempotency marker
+
+Written to `.codebyplan.json` after setup completes:
+
+```json
+{
+  "shipment": {
+    "surfaces": {
+      "supabase": {
+        "branching_configured": {
+          "enabled_at": "2026-05-20T10:00:00Z",
+          "github_app_installed": true,
+          "required_check_enforced": true
+        }
+      }
+    }
+  }
+}
+```
+
+Re-running `/cbp-ship-configure --surface=supabase` reads this marker and skips steps
+already completed. Re-running `/cbp-supabase-setup` directly also respects it.

package/templates/skills/cbp-ship-configure/reference/tauri-desktop.md

@@ -0,0 +1,181 @@
+# Configure: tauri-desktop
+
+Walkthrough for first-time Tauri desktop release pipeline setup.
+
+This walkthrough sets up a complete Tauri desktop release pipeline (signing, notarization, GitHub Actions tag-trigger) step by step.
+
+## Prerequisites
+
+- Apple Developer Program enrollment (for macOS signing/notarization)
+- (Optional) Windows code signing certificate
+- (Optional) Linux: no signing prereq, only AppImage
+- Tauri 2.x app already scaffolded in `src-tauri/`
+
+## Probe
+
+```bash
+test -f src-tauri/tauri.conf.json || { echo "No Tauri app detected"; exit 1; }
+which gh || { echo "Install gh CLI: brew install gh"; exit 1; }
+gh auth status || { echo "Run: gh auth login"; exit 1; }
+which jq
+```
+
+## Setup walkthrough
+
+### Step 1/7: Generate Tauri updater signing key
+
+```bash
+mkdir -p ~/.tauri
+APP_SLUG=$(jq -r .productName src-tauri/tauri.conf.json | tr '[:upper:] ' '[:lower:]-')
+npx tauri signer generate -w ~/.tauri/${APP_SLUG}.key
+```
+
+Set a passphrase when prompted. **Save the passphrase** — you'll add it as a GH secret.
+
+The command outputs a `pubkey` value. Add it to `src-tauri/tauri.conf.json`:
+
+```json
+{
+  "tauri": {
+    "bundle": {
+      "updater": {
+        "active": true,
+        "endpoints": ["https://your-blob-host/latest.json"],
+        "pubkey": "<paste here>"
+      }
+    }
+  }
+}
+```
+
+### Step 2/7: Apple Developer ID Application certificate
+
+If you don't have one yet:
+
+```
+1. Go to https://developer.apple.com/account/resources/certificates/add
+2. Choose 'Developer ID Application'
+3. Generate CSR via Keychain Access → Certificate Assistant → Request a Certificate from a Certificate Authority
+4. Upload CSR, download the .cer file
+5. Double-click .cer to install in Keychain
+6. In Keychain Access, find 'Developer ID Application: <Your Name>' → right-click → Export
+7. Choose .p12 format, set a password
+```
+
+Then:
+
+```bash
+# Base64 encode for GH secret
+base64 -i DeveloperIDApplication.p12 | pbcopy
+# Identity name (paste into APPLE_SIGNING_IDENTITY)
+security find-identity -p codesigning -v | grep "Developer ID Application"
+```
+
+### Step 3/7: App Store Connect API key (for notarization)
+
+Same key as `expo-mobile` setup if you already did that. Otherwise:
+
+```
+1. https://appstoreconnect.apple.com/access/api
+2. Generate Key, role 'Developer' (or higher)
+3. Download .p8 file (one chance only)
+4. Note Key ID and Issuer ID
+```
+
+### Step 4/7: Vercel Blob token (for hosting downloads + updater manifest)
+
+```
+1. https://vercel.com/dashboard → Storage → Blob → Create
+2. Connect to your Vercel project
+3. Copy the BLOB_READ_WRITE_TOKEN value
+```
+
+(Skip if you're hosting downloads on GH Releases only — the updater manifest can be served from there.)
+
+### Step 5/7: Upload all 9 GH secrets
+
+The skill walks the user through `gh secret set` for each:
+
+```bash
+REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
+
+gh secret set TAURI_SIGNING_PRIVATE_KEY -R "$REPO" < ~/.tauri/${APP_SLUG}.key
+gh secret set TAURI_SIGNING_PRIVATE_KEY_PASSWORD -R "$REPO"   # paste passphrase
+gh secret set APPLE_CERTIFICATE -R "$REPO"                    # paste base64 .p12
+gh secret set APPLE_CERTIFICATE_PASSWORD -R "$REPO"           # paste .p12 password
+gh secret set APPLE_SIGNING_IDENTITY -R "$REPO"               # paste 'Developer ID Application: ...'
+gh secret set APPLE_API_ISSUER -R "$REPO"                     # paste UUID
+gh secret set APPLE_API_KEY -R "$REPO"                        # paste 10-char Key ID
+gh secret set APPLE_API_KEY_CONTENT -R "$REPO"                # paste raw .p8 content (with BEGIN/END)
+gh secret set BLOB_READ_WRITE_TOKEN -R "$REPO"                # paste from step 4 (skip if not using)
+```
+
+After each, verify:
+
+```bash
+gh secret list -R "$REPO" | grep -E "TAURI|APPLE|BLOB"
+# Expect: 9 entries
+```
+
+### Step 6/7: Scaffold the workflow
+
+Copy the template:
+
+```bash
+cp ${CLAUDE_PLUGIN_ROOT}/skills/ship/templates/workflow-tauri-release.yml .github/workflows/release-desktop.yml
+```
+
+Customize the matrix (which platforms to build) and the artifact upload step.
+
+The workflow triggers on `v*.*.*` tag push. It:
+
+1. Checks out
+2. Installs Rust + Node + pnpm
+3. Restores Apple cert from `APPLE_CERTIFICATE` secret
+4. Writes `APPLE_API_KEY_CONTENT` to `~/private_keys/AuthKey.p8`
+5. Builds via `tauri-action`
+6. Uploads .dmg / .msi / .AppImage to GH Releases
+7. Updates `latest.json` (Tauri updater manifest) and uploads to Vercel Blob (if configured)
+
+### Step 7/7: Persist + dry-run
+
+`.codebyplan/shipment.json`:
+
+```json
+{
+  "surfaces": {
+    "tauri-desktop": {
+      "configured_at": "<now>",
+      "app_path": "apps/desktop",
+      "platforms": ["macos-arm64", "macos-x64"],
+      "updater_endpoint": "https://your-blob-host/latest.json",
+      "versioning": "manual"
+    }
+  }
+}
+```
+
+Test with a dry-run tag (the workflow runs but you can delete the release after):
+
+```bash
+git tag v0.0.0-test
+git push origin v0.0.0-test
+gh run watch
+# After verification:
+gh release delete v0.0.0-test --yes
+git push origin :v0.0.0-test
+git tag -d v0.0.0-test
+```
+
+## Done
+
+Surface is ready. `/cbp-ship` will offer desktop release when version bumps.
+
+## Common setup issues
+
+| Symptom | Fix |
+|---|---|
+| Notarization step times out | `notarytool` slow under heavy queue; the workflow waits up to 30min, usually completes |
+| "Invalid p12 password" | Test locally: `security import DeveloperIDApplication.p12 -P "$PASS"` |
+| `latest.json` not updating in Vercel Blob | Check `BLOB_READ_WRITE_TOKEN` scope (must be read+write, not read-only) |
+| Workflow fails on Linux runner | Common: missing `webkit2gtk-4.1` system dep; add to apt install step |

package/templates/skills/cbp-ship-configure/reference/vercel.md

@@ -0,0 +1,117 @@
+# Configure: vercel-web
+
+Walkthrough for first-time Vercel link.
+
+## Prerequisites
+
+- Vercel account (free tier OK for hobby; Pro for teams)
+- For monorepo: decide which app folder gets linked (each app needs its own link)
+
+## Probe
+
+```bash
+which vercel || { echo "Install: npm i -g vercel"; exit 1; }
+vercel --version
+vercel whoami || { echo "Run: vercel login"; exit 1; }
+```
+
+## Setup walkthrough
+
+### Step 1/6: Pick the app folder
+
+If monorepo, ask user which `apps/*` directory. If single-app repo, use the repo root.
+
+### Step 2/6: Run `vercel link`
+
+```
+You'll run: vercel link
+
+This creates .vercel/project.json. Choose:
+- Existing project: pick from list
+- New project: type name, accept defaults
+
+Press Enter to run, or 'skip' to do it yourself in another terminal.
+```
+
+If user runs it in this terminal, observe the resulting `.vercel/project.json`.
+
+### Step 3/6: Configure framework settings
+
+If Next.js + monorepo, set:
+
+```
+Vercel dashboard → project → Settings → General:
+- Framework Preset: Next.js
+- Root Directory: apps/{instance}
+- Build Command: cd ../.. && pnpm turbo build --filter={instance}
+- Install Command: cd ../.. && pnpm install --frozen-lockfile
+- Output Directory: (leave default)
+```
+
+### Step 4/6: Sync env vars
+
+```bash
+# Read from .env.example for the keys
+KEYS=$(grep -E '^[A-Z_]+=' "$APP_PATH/.env.example" | cut -d= -f1)
+echo "Vars to set in Vercel: $KEYS"
+
+# For each, prompt user — values come from their secret store, not this skill
+```
+
+For each key, instruct:
+
+```
+Set $KEY in Vercel:
+   vercel env add $KEY production
+   vercel env add $KEY preview
+
+(or via dashboard → Settings → Environment Variables)
+```
+
+### Step 5/6: Verify GH integration
+
+```bash
+vercel git connect 2>&1 | head -5
+# Should report the linked GitHub repo. If not connected:
+echo "Vercel dashboard → project → Settings → Git → Connect GitHub Repository"
+```
+
+### Step 6/6: Persist + verify
+
+Write `.codebyplan/shipment.json`:
+
+```json
+{
+  "surfaces": {
+    "vercel-web": {
+      "configured_at": "<now>",
+      "instance": "apps/web",
+      "project_id": "<from .vercel/project.json>",
+      "org_id": "<from .vercel/project.json>",
+      "framework": "nextjs",
+      "production_branch": "<branch_config.production>"
+    }
+  }
+}
+```
+
+Verify:
+
+```bash
+PROJECT_ID=$(jq -r '.surfaces."vercel-web".project_id' .codebyplan/shipment.json)
+vercel inspect "$PROJECT_ID" --json | jq -r '.name, .latestDeployments[0].readyState'
+```
+
+Expect: project name + `READY` (or `BUILDING` if mid-deploy).
+
+## Done
+
+Surface is ready. `/cbp-ship` can now deploy this app.
+
+## Common setup issues
+
+| Symptom | Fix |
+|---|---|
+| `vercel link` errors "team not found" | Re-login: `vercel logout && vercel login` |
+| Build fails on first deploy | Verify Root Directory and Build Command match monorepo layout |
+| "No Production Deployment" status | Push to production branch (or run `vercel --prod` once) to seed |