codebyplan 1.5.1 → 1.9.0

package/templates/skills/cbp-ship/reference/surface-railway.md

@@ -0,0 +1,152 @@
+# Surface: railway-backend
+
+Deploy a backend service (NestJS / Node / Bun / Python) to Railway.
+
+Railway is the standard backend platform for the CBP family (per architectural decision 2026-04-29). Other Docker-friendly platforms (Fly, Render, Heroku) can be added as separate surfaces if needed — Railway is the default.
+
+## Detection
+
+Signals (any of):
+
+- `railway.toml` or `railway.json` at app root
+- `.railway/` directory at app root
+- `Dockerfile` AND `package.json` with non-frontend deps (no `next`, no `react-native`) AND not under workspace `packages/`
+
+## Configured indicators
+
+`configured: true` requires:
+
+1. `railway.toml` or `.railway/config.json` present with `project` ID
+2. `railway` CLI installed (`railway --version` succeeds)
+3. `railway whoami` returns a logged-in user
+4. `.codebyplan/shipment.json` `.surfaces.railway-backend` block has `project_id` AND `service_id` AND `environment_id`
+
+## Variants
+
+| Variant | When |
+|---|---|
+| `deploy` | Service code or Dockerfile changed since last shipment |
+| `skip` | No backend changes |
+
+Detection uses git diff: if any path under the service directory changed between the prior shipment SHA and the current ship SHA, mark `deploy`.
+
+## STEPS — deploy variant
+
+Railway has two deployment modes:
+
+- **Auto-deploy on push** — preferred. Linked to a GH branch; pushes trigger deploys via webhook.
+- **Manual `railway up`** — fallback when GH integration isn't desired.
+
+Detection: `railway service --json | jq .repoConfig` — if non-null, it's auto-deploy. Otherwise manual.
+
+### Auto-deploy mode
+
+1. **Verify GH integration is healthy**:
+   ```bash
+   railway service --json | jq -r .repoConfig.repoLink
+   # Should match the current repo
+   ```
+
+2. **Wait for the deploy webhook to fire** (up to 30s after PR merge):
+   ```bash
+   timeout 60 bash -c "while ! railway logs --json 2>/dev/null | jq -e '.[0].timestamp > \"$(date -u -v-1M +%FT%T)\"'; do sleep 5; done"
+   ```
+
+3. **Get the deployment ID**:
+   ```bash
+   DEPLOY_ID=$(railway deployment list --json | jq -r '.[0].id')
+   ```
+
+4. **Wait for deployment SUCCESS state**:
+   ```bash
+   timeout 600 bash -c "while [ \"\$(railway deployment status \"$DEPLOY_ID\" --json | jq -r .status)\" != \"SUCCESS\" ]; do
+     STATUS=\$(railway deployment status \"$DEPLOY_ID\" --json | jq -r .status)
+     [ \"\$STATUS\" = \"FAILED\" ] && exit 1
+     sleep 10
+   done"
+   ```
+
+5. **Capture URL**:
+   ```bash
+   URL=$(railway domain --json | jq -r '.[0].domain' | head -1)
+   ```
+
+### Manual deploy mode
+
+1. **Confirm with user**:
+   ```
+   Railway is configured for manual deploy. Run: railway up
+   This builds locally + uploads + deploys (5-10 min).
+   A) Run `railway up` — start the deploy
+   B) Skip — deploy manually later
+   ```
+
+2. **Run the deploy**:
+   ```bash
+   cd "$APP_PATH"
+   railway up --detach
+   ```
+
+3. **Steps 3-5 same as auto-deploy mode**.
+
+## Verification
+
+`scripts/verify-railway.sh`:
+
+```bash
+DEPLOY_ID="$1"
+URL="$2"
+
+# Deployment status
+STATUS=$(railway deployment status "$DEPLOY_ID" --json | jq -r .status)
+[ "$STATUS" = "SUCCESS" ] || { echo "Deploy not successful: $STATUS"; exit 1; }
+
+# Health endpoint (if configured)
+if [ -n "$URL" ]; then
+  HEALTH=$(curl -sI -m 10 "https://$URL/health" 2>/dev/null | head -1 | awk '{print $2}')
+  [ "$HEALTH" = "200" ] || echo "WARN: /health returned $HEALTH (may not be implemented)"
+fi
+
+echo "OK"
+```
+
+## Common failures
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Deploy fails at "Building" | Dockerfile build error | `railway logs --build` — usually missing system dep or wrong Node version |
+| Deploy succeeds, app crashes on start | Missing env var | `railway variables` — compare to `.env.example` |
+| Health endpoint times out | Service not listening on Railway's `$PORT` | Bind to `process.env.PORT` not hardcoded port |
+| GH webhook not firing | Disconnect or branch filter mismatch | Railway dashboard → service → Settings → Source → reconnect |
+| OOM during build | Large node_modules | Add `.dockerignore`; use multi-stage build |
+
+## Rollback
+
+```bash
+railway redeploy <prior-deployment-id>
+```
+
+The orchestrator surfaces this when verification fails:
+
+```
+Railway deployment FAILED.
+Options:
+A) Retry — sometimes transient
+B) Rollback to deployment <prior-id> (last successful)
+C) Investigate logs — railway logs --build / --runtime
+```
+
+## Multi-service projects
+
+A Railway project can have multiple services (e.g., `api`, `worker`, `cron`). Each shipment surface is per-service. The detection emits one entry per service:
+
+```json
+{ "id": "railway-backend", "instance": "apps/backend",  "service_id": "svc_abc", ... }
+{ "id": "railway-backend", "instance": "apps/worker",   "service_id": "svc_def", ... }
+```
+
+The orchestrator deploys each independently.
+
+## Configure-once setup
+
+See `${CLAUDE_PLUGIN_ROOT}/skills/ship-configure/reference/railway-backend.md` for first-time setup (railway login, project creation/link, env var sync, GH integration, custom domain, health endpoint config).

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

@@ -0,0 +1,178 @@
+# Surface: supabase
+
+Push pending database migrations to the linked Supabase project.
+
+This is the most consequential shipment surface — schema mismatches break web/backend immediately. Migration push is **always interactive** with explicit user review of the diff before applying.
+
+## Detection
+
+Signals:
+
+- `supabase/` directory with `config.toml`
+- `supabase/migrations/*.sql` — count of files newer than `last_shipped_migration_version` in `.codebyplan/shipment.json` `.surfaces.supabase`
+
+## Configured indicators
+
+`configured: true` requires:
+
+1. `supabase/config.toml` parseable with `project_id` field
+2. `supabase` CLI installed (`supabase --version` succeeds)
+3. `supabase projects list` succeeds (CLI authenticated)
+4. `.codebyplan/shipment.json` `.surfaces.supabase` block has `project_ref`
+
+Library docs via DocsByPlan MCP (`resolve_library_id('supabase')`).
+
+## Variants
+
+| Variant | When |
+|---|---|
+| `push-migrations` | At least one migration file is newer than `last_shipped_migration_version` |
+| `skip` | No new migrations |
+
+## STEPS — push-migrations variant
+
+This is **always interactive**. The orchestrator does NOT silently apply migrations even with confirmation up front, because the diff might surprise the user (auto-generated migrations sometimes include unintended changes).
+
+1. **List pending migrations**:
+   ```bash
+   PROJECT_REF=$(jq -r '.surfaces.supabase.project_ref' .codebyplan/shipment.json)
+   LAST_VERSION=$(jq -r '.surfaces.supabase.last_shipped_migration_version // ""' .codebyplan/shipment.json)
+
+   PENDING=$(ls supabase/migrations/*.sql | sort)
+   if [ -n "$LAST_VERSION" ]; then
+     PENDING=$(echo "$PENDING" | awk -v cutoff="$LAST_VERSION" '$0 > "supabase/migrations/" cutoff')
+   fi
+   echo "$PENDING"
+   ```
+
+2. **Show user the migration list** + counts:
+   ```
+   ## Pending migrations (4)
+
+   - 0083_add_user_avatars.sql       (12 lines)
+   - 0084_index_session_lookups.sql  (4 lines)
+   - 0085_rls_share_links.sql        (28 lines)
+   - 0086_view_active_users.sql      (8 lines)
+
+   Press Enter to review each diff individually, or type 'all' to see them concatenated.
+   ```
+
+3. **Walk through each migration** via AskUserQuestion (one per file):
+   ```
+   ### 0083_add_user_avatars.sql
+
+   ```sql
+   ALTER TABLE users ADD COLUMN avatar_url text;
+   CREATE INDEX users_avatar_url_idx ON users(avatar_url) WHERE avatar_url IS NOT NULL;
+   ```
+
+   Approve this migration?
+   A) Approve — include in push
+   B) Skip this one (manual review needed)
+   C) Abort — stop shipment, don't push anything
+   ```
+
+   The user reviews each file. If they pick C on any, halt — do NOT continue with subsequent surfaces.
+
+4. **Generate diff against the live project** for safety:
+   ```bash
+   supabase db diff --use-migra --schema public,auth
+   ```
+
+   This compares local migrations to remote state. If the diff shows things NOT in the migrations (drift on the remote), HALT and surface to the user — remote drift means someone applied changes via the dashboard, and we shouldn't blindly push.
+
+5. **Push approved migrations**:
+   ```bash
+   supabase db push --include-all
+   ```
+
+   If push fails partway (e.g., migration 0084 errors), Supabase rolls back to the last successful migration. Surface the failure:
+   ```
+   Migration push FAILED at 0084_index_session_lookups.sql
+   Reason: <error from supabase>
+
+   The migrations applied successfully:
+   ✓ 0083_add_user_avatars.sql
+
+   The remaining migrations (0085, 0086) were NOT applied.
+
+   Options:
+   A) Fix migration 0084 in code, re-run /cbp-ship
+   B) Skip 0084 and proceed with 0085+0086 (use --include-files)
+   C) Abort — schema is partially-shipped; revert the applied migration manually if needed
+   ```
+
+6. **Regenerate TypeScript types** (if the project uses generated types):
+   ```bash
+   if [ -f "supabase/functions/_shared/db.types.ts" ] || [ -f "packages/supabase/types.ts" ]; then
+     supabase gen types typescript --project-id "$PROJECT_REF" > "$TYPES_PATH"
+     # If diff exists, surface to user — types changes may need to be committed
+     if ! git diff --quiet "$TYPES_PATH"; then
+       echo "Types regenerated — diff present. Commit before completing checkpoint."
+     fi
+   fi
+   ```
+
+7. **Update the last-shipped marker**:
+   ```bash
+   LAST_APPLIED=$(echo "$PENDING" | tail -1 | xargs basename)
+   jq --arg v "$LAST_APPLIED" '.surfaces.supabase.last_shipped_migration_version = $v' .codebyplan/shipment.json > .codebyplan/shipment.json.tmp
+   mv .codebyplan/shipment.json.tmp .codebyplan/shipment.json
+   ```
+
+8. **Result**:
+   ```json
+   {
+     "status": "verified",
+     "migrations_applied": ["0083_...", "0084_...", "0085_...", "0086_..."],
+     "types_regenerated": true,
+     "project_ref": "abcdefgh"
+   }
+   ```
+
+## Verification
+
+`scripts/verify-supabase.sh`:
+
+```bash
+PROJECT_REF="$1"
+EXPECTED_LAST="$2"
+
+# All listed migrations are recorded in supabase_migrations table
+APPLIED=$(supabase migration list --remote --linked 2>/dev/null | grep -F "$EXPECTED_LAST" | wc -l)
+[ "$APPLIED" -gt 0 ] || { echo "Migration $EXPECTED_LAST not found on remote"; exit 1; }
+
+# No drift
+DRIFT=$(supabase db diff --use-migra 2>/dev/null | grep -v "^--" | grep -c .)
+[ "$DRIFT" -eq 0 ] || { echo "WARN: $DRIFT lines of drift between local migrations and remote"; }
+
+echo "OK"
+```
+
+## Common failures
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `db push` fails with permission error | Service role token missing scopes | `supabase login` again, ensure access token has full project access |
+| Migration fails on `RAISE EXCEPTION` | Data assertion failure | Inspect data; usually means a NOT NULL constraint with existing NULLs |
+| RLS policy fails to apply | References non-existent role | Migrations must be self-contained; check `supabase/seed.sql` for role creation |
+| Drift detected | Someone applied changes via dashboard | Pull dashboard changes into a migration: `supabase db diff -f resolve_drift` |
+| Types regen breaks compilation | New column not exposed via API | Add the table/column to `exposed_schemas` in `config.toml` |
+
+## Rollback
+
+There's no clean rollback for applied migrations. Two paths:
+
+1. **Forward-only revert** — write a new migration that undoes the change, push it
+2. **Point-in-time restore** — Supabase paid tier; via dashboard
+
+The orchestrator surfaces #1 as the recommended path:
+
+```
+Migration cannot be auto-rolled-back.
+Recommended: write a new migration that reverses the schema change, then re-run /cbp-ship.
+```
+
+## Configure-once setup
+
+See `${CLAUDE_PLUGIN_ROOT}/skills/ship-configure/reference/supabase.md` for first-time setup (supabase login, project link, types path config, optional auto-types-on-edit).

package/templates/skills/cbp-ship/reference/surface-tauri.md

@@ -0,0 +1,138 @@
+# Surface: tauri-desktop
+
+Build, sign, notarize, and release a Tauri desktop app via GitHub Actions tag-trigger.
+
+This surface file is the orchestrator's interface to the Tauri release pipeline — secrets, CI workflow, signing, notarization, and gotchas are all covered in the sections below.
+
+## Detection
+
+Signals:
+
+- `src-tauri/tauri.conf.json` present
+- `apps/desktop/src-tauri/` (monorepo) — instance is `apps/desktop`
+
+## Configured indicators
+
+`configured: true` requires:
+
+1. `src-tauri/tauri.conf.json` parseable, with `productName` + `version`
+2. `.github/workflows/release-desktop.yml` (or similar tag-trigger workflow) present
+3. Required GitHub secrets set (per architecture doc — 9 secrets for the WBP setup)
+4. `gh auth status` succeeds (CLI authenticated)
+
+Probe: `gh secret list -R OWNER/REPO` and check that the 9 secret names from the architecture doc are present.
+
+## Variants
+
+| Variant | When |
+|---|---|
+| `tag-and-release` | Version bump detected in `src-tauri/tauri.conf.json` `version` OR root `package.json` |
+| `skip` | No version change since last shipment — desktop releases are tag-driven, not branch-driven |
+
+## STEPS — tag-and-release variant
+
+1. **Read version from tauri config**:
+   ```bash
+   VERSION=$(jq -r .version "$APP_PATH/src-tauri/tauri.conf.json")
+   ```
+
+2. **Verify tag doesn't already exist**:
+   ```bash
+   git fetch origin --tags
+   if git rev-parse "v$VERSION" >/dev/null 2>&1; then
+     echo "Tag v$VERSION already exists — skip or bump version"; exit 1
+   fi
+   ```
+
+3. **Confirm with user** via AskUserQuestion:
+   ```
+   Push tag v$VERSION? This triggers GH Actions build + sign + notarize + release.
+   The build takes ~15 min. You'll receive a GH Releases page when complete.
+   A) Push tag — start the release
+   B) Skip — bump version in another commit first
+   ```
+
+4. **Push the tag**:
+   ```bash
+   git tag -a "v$VERSION" -m "Release v$VERSION"
+   git push origin "v$VERSION"
+   ```
+
+5. **Get the workflow run** triggered by the tag:
+   ```bash
+   sleep 5  # GH Actions registration lag
+   RUN_ID=$(gh run list --workflow=release-desktop.yml --limit 1 --json databaseId,headBranch,event \
+     | jq -r ".[] | select(.event == \"push\" and .headBranch == \"v$VERSION\") | .databaseId")
+   ```
+
+6. **Watch the run** (15 min cap):
+   ```bash
+   gh run watch "$RUN_ID" --exit-status
+   ```
+
+7. **Verify GH Release was created**:
+   ```bash
+   gh release view "v$VERSION" --json assets,publishedAt | jq
+   ```
+   Expect: 2 assets minimum (ARM .dmg + Intel .dmg) for macOS-only builds; more for Win/Linux if configured.
+
+8. **Result**:
+   ```json
+   {
+     "status": "verified",
+     "version": "v1.4.0",
+     "release_url": "https://github.com/OWNER/REPO/releases/tag/v1.4.0",
+     "assets": ["WorkByPlan_1.4.0_aarch64.dmg", "WorkByPlan_1.4.0_x64.dmg"],
+     "workflow_run_id": "1234567890"
+   }
+   ```
+
+## Verification
+
+`scripts/verify-tauri.sh`:
+
+```bash
+VERSION="$1"
+
+# Tag exists locally + remote
+git rev-parse "v$VERSION" >/dev/null 2>&1 || { echo "Tag missing"; exit 1; }
+git ls-remote --tags origin "v$VERSION" | grep -q . || { echo "Tag not pushed"; exit 1; }
+
+# GH Release published
+PUBLISHED=$(gh release view "v$VERSION" --json publishedAt -q .publishedAt 2>/dev/null)
+[ -n "$PUBLISHED" ] || { echo "Release not published"; exit 1; }
+
+# At least one signed .dmg in assets
+ASSETS=$(gh release view "v$VERSION" --json assets -q '.assets | length')
+[ "$ASSETS" -ge 1 ] || { echo "No release assets"; exit 1; }
+
+# Updater manifest (latest.json) updated — Tauri auto-update needs this
+gh release view "v$VERSION" --json assets -q '.assets[].name' | grep -q "latest.json" \
+  || echo "WARN: latest.json missing from release — auto-update may not work"
+
+echo "OK"
+```
+
+## Common failures
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Workflow fails at "Notarize" step | Apple API key file path issue | See architecture doc § "Apple Notarization Key" — `.p8` content must be written to a file path, not passed as string |
+| `latest.json` missing | Tauri updater config disabled in tauri.conf.json | Enable `tauri.bundle.updater` |
+| ARM/Intel asset missing | matrix build for one arch failed | Check workflow logs; commonly Rust toolchain issue on the failed runner |
+| "Invalid signing identity" | `APPLE_SIGNING_IDENTITY` secret has wrong format | Must be exact match: `Developer ID Application: Name (TEAMID)` |
+| Public download URL broken | Vercel Blob upload step failed | Check `BLOB_READ_WRITE_TOKEN` secret + Vercel storage quota |
+
+## Rollback
+
+Tauri's auto-updater honors the most recent `latest.json` published. To rollback:
+
+1. Delete the bad release: `gh release delete v$VERSION --yes`
+2. Republish a prior tag: `gh release create v$PRIOR --notes "Republish after rollback" $PRIOR_ASSETS`
+3. The auto-updater will roll users back at their next launch
+
+The orchestrator surfaces this as an option when verification fails.
+
+## Configure-once setup
+
+See `${CLAUDE_PLUGIN_ROOT}/skills/ship-configure/reference/tauri-desktop.md` for first-time setup (Apple Developer cert, key generation, secrets upload, workflow scaffolding).

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

@@ -0,0 +1,124 @@
+# Surface: vercel-web
+
+Deploy a Next.js (or static) app to Vercel.
+
+## Detection
+
+Signals (any one is sufficient):
+
+- `vercel.json` at app root
+- `.vercel/project.json` at app root (links repo to Vercel project)
+- App directory contains `next` in `package.json` dependencies AND no other surface signal claims it
+
+A repo can have multiple `vercel-web` instances — one per app folder under `apps/*`.
+
+## Configured indicators
+
+`configured: true` requires:
+
+1. `.vercel/project.json` present with `projectId` and `orgId`
+2. Vercel CLI authenticated (`vercel whoami` succeeds)
+3. `.codebyplan/shipment.json` `.surfaces.vercel-web.{instance}` block (optional but recommended)
+
+If `.vercel/project.json` is missing → `configured: false`, reason "not linked to Vercel project — run /cbp-ship-configure".
+
+## Variant: production
+
+Default for shipping to PRODUCTION branch (per `branch_config.production`). Vercel auto-deploys on push to the linked production branch — this variant **observes** the auto-deploy, doesn't trigger it.
+
+### STEPS — production variant
+
+1. **Read project ID** from `.vercel/project.json`:
+   ```bash
+   PROJECT_ID=$(jq -r .projectId .vercel/project.json)
+   ORG_ID=$(jq -r .orgId .vercel/project.json)
+   ```
+
+2. **Get the deployment triggered by the merge commit**:
+   ```bash
+   MERGE_SHA=$(git rev-parse HEAD)
+   DEPLOYMENT=$(vercel ls --json 2>/dev/null | jq -r ".[] | select(.meta.githubCommitSha == \"$MERGE_SHA\") | .uid" | head -1)
+   ```
+
+   If no deployment found within 60s, Vercel is slow — wait up to 5min:
+   ```bash
+   timeout 300 bash -c "while ! vercel ls --json | jq -e '.[] | select(.meta.githubCommitSha == \"$MERGE_SHA\")' > /dev/null; do sleep 10; done"
+   ```
+
+3. **Wait for READY state**:
+   ```bash
+   vercel inspect "$DEPLOYMENT" --wait
+   ```
+
+4. **Capture URL + readyState**:
+   ```bash
+   STATUS=$(vercel inspect "$DEPLOYMENT" --json | jq -r '.readyState')
+   URL=$(vercel inspect "$DEPLOYMENT" --json | jq -r '.alias[0] // .url')
+   ```
+
+5. **Result**: `{ status: STATUS, url: URL, deployment_id: DEPLOYMENT }` to orchestrator.
+
+## Variant: manual-redeploy
+
+For "the auto-deploy failed, force a redeploy" path. User triggers explicitly.
+
+### STEPS — manual-redeploy variant
+
+```bash
+cd "$APP_PATH"
+vercel --prod --yes
+```
+
+Capture deployment ID from output, then run Steps 3–5 from production variant.
+
+## Variant: preview
+
+Vercel auto-creates a preview deployment per PR. The orchestrator typically does NOT need to trigger anything for staging shipments — but it CAN verify the preview deployment for the integration branch:
+
+```bash
+INTEGRATION=$(jq -r .branch_config.integration .codebyplan/git.json)
+INTEGRATION_SHA=$(git rev-parse "origin/$INTEGRATION")
+vercel ls --json | jq ".[] | select(.meta.githubCommitSha == \"$INTEGRATION_SHA\" and .target == \"preview\")"
+```
+
+## Verification
+
+`scripts/verify-vercel.sh` does:
+
+1. `vercel inspect "$DEPLOYMENT_ID" --json | jq -r .readyState` returns `READY`
+2. `curl -sI "$URL" | head -1` returns `HTTP/2 200` (or 401 for password-protected previews — also success)
+3. If `apps/{instance}/public/health.json` or `/api/health` exists, hit it: expect 200
+
+Timeouts:
+- Build: 5 min (Vercel Hobby is slower; allow 8 min)
+- HTTP probe: 30s
+
+## Common failures
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `vercel ls` shows no deployment for the merge SHA | GitHub integration not connected, or push didn't trigger | Check Vercel dashboard → Settings → Git; reconnect if needed |
+| Build fails with "Module not found" | Monorepo root not configured | In Vercel project settings: Build Command → `cd ../.. && pnpm turbo build --filter={instance}`, Root Directory → `apps/{instance}` |
+| Preview URL 404s | Project paused or env var missing | Check Vercel logs for the deployment; common: missing `DATABASE_URL` |
+| Build succeeds but page is blank | Production env vars missing | `vercel env ls production` — compare to `.env.example` |
+
+## Rollback
+
+```bash
+vercel rollback                    # interactive: pick a prior deployment
+vercel promote "$PRIOR_DEPLOYMENT" # promote a specific deployment to production
+```
+
+The orchestrator surfaces this as an option when a verification fails:
+
+```
+Vercel deployment failed verification.
+Options:
+A) Retry — the deploy may complete async
+B) Rollback to prior production deployment
+C) Investigate manually — show me the build logs
+```
+
+## Configure-once setup
+
+See `${CLAUDE_PLUGIN_ROOT}/skills/ship-configure/reference/vercel.md` for first-time setup (vercel link, env var sync, GH integration verification).