codebyplan 1.5.0 → 1.8.0

package/templates/skills/cbp-ship-configure/reference/vscode-ext.md

@@ -0,0 +1,155 @@
+# Configure: vscode-ext
+
+Walkthrough for first-time VS Code Marketplace publish setup.
+
+## Prerequisites
+
+- Microsoft account (free) — for Azure DevOps + marketplace publisher
+- Azure DevOps organization (free) — https://dev.azure.com
+- Marketplace publisher account — https://marketplace.visualstudio.com/manage
+
+## Probe
+
+```bash
+test -f package.json && jq -e '.engines.vscode' package.json >/dev/null || { echo "Not a VS Code extension"; exit 1; }
+which npx
+npx @vscode/vsce --version || { echo "Will install vsce on first use (npm i -g @vscode/vsce)"; }
+```
+
+## Setup walkthrough
+
+### Step 1/6: Create publisher (if first time)
+
+Direct user to:
+
+```
+1. Go to https://marketplace.visualstudio.com/manage/createpublisher
+2. Choose a publisher ID (lowercase, hyphens — must be globally unique)
+3. Enter display name + email
+
+Reply with the publisher ID when done.
+```
+
+### Step 2/6: Generate Personal Access Token (PAT)
+
+```
+1. Go to https://dev.azure.com/<your-org>/_usersSettings/tokens
+2. Click 'New Token'
+3. Name: 'vsce publish'
+4. Organization: 'All accessible organizations' (CRITICAL — not just your org)
+5. Expiration: 1 year (note: PATs expire; you'll need to rotate)
+6. Scopes: Custom Defined → Marketplace → Manage
+
+Click Create. Copy the token.
+
+Reply 'done' when copied. Keep the token in a safe place — you can't see it again.
+```
+
+### Step 3/6: Verify PAT works
+
+```bash
+PUBLISHER=$(jq -r .publisher package.json)
+npx @vscode/vsce verify-pat "$PUBLISHER"
+# Will prompt for the PAT
+```
+
+If verification fails, walk the user through:
+
+- Wrong scope (not Marketplace → Manage) — most common
+- Token belongs to wrong organization (must be "All accessible")
+- Token expired
+
+### Step 4/6: Verify package.json metadata
+
+VS Code Marketplace requires more metadata than npm:
+
+```
+Required:
+  name              ✓
+  displayName       ✓ (human-readable name)
+  description       ✓ (1-2 sentences)
+  publisher         ✓ (matches step 1)
+  version           ✓
+  engines.vscode    ✓ (minimum version, e.g., "^1.85.0")
+  categories        ✓ (e.g., ["Programming Languages", "Linters"])
+  icon              ✓ (PNG ≥128×128, in repo root)
+  repository        ✓ (public GH URL)
+
+Recommended:
+  keywords          (improves search)
+  galleryBanner     (color theme)
+  activationEvents  (when extension activates)
+  contributes       (commands, settings, etc.)
+```
+
+### Step 5/6: Validate `.vscodeignore`
+
+VS Code packages can balloon if `.vscodeignore` is too lax:
+
+```bash
+cd "$EXT_PATH"
+if [ ! -f .vscodeignore ]; then
+  cp ${CLAUDE_PLUGIN_ROOT}/skills/ship/templates/vscodeignore .vscodeignore
+fi
+
+npx @vscode/vsce ls
+# Lists what would be packaged. If size > 5MB or includes node_modules, fix .vscodeignore
+```
+
+A reasonable `.vscodeignore`:
+
+```
+.vscode/**
+.vscode-test/**
+src/**
+.gitignore
+.yarnrc
+vsc-extension-quickstart.md
+**/tsconfig.json
+**/.eslintrc.*
+**/*.map
+**/*.ts
+node_modules
+.git/**
+*.test.*
+*.spec.*
+```
+
+### Step 6/6: Persist + dry-run
+
+```json
+{
+  "surfaces": {
+    "vscode-ext": {
+      "configured_at": "<now>",
+      "ext_path": "apps/vscode",
+      "publisher": "<publisher>",
+      "extension_id": "<publisher>.<name>",
+      "marketplace_url": "https://marketplace.visualstudio.com/items?itemName=<publisher>.<name>",
+      "versioning": "manual"
+    }
+  }
+}
+```
+
+Dry-run package:
+
+```bash
+cd "$EXT_PATH"
+npx @vscode/vsce package --no-yarn -o /tmp/dryrun.vsix
+ls -lh /tmp/dryrun.vsix
+# Sanity-check size
+```
+
+## Done
+
+Surface is ready. `/cbp-ship` will offer marketplace publish when version bumps.
+
+## Common setup issues
+
+| Symptom | Fix |
+|---|---|
+| `vsce verify-pat` fails | PAT scope wrong: must be Marketplace → Manage, not Code → Read |
+| Icon validation fails | PNG, ≥128×128 (256×256 recommended), no transparency in marketplace listing |
+| README rendering broken in marketplace | Marketplace renders GitHub-flavored markdown but with limited image hosts; use raw.githubusercontent.com URLs |
+| "Extension contains script" warning | Inline `<script>` in webview HTML — use CSP nonces |

package/templates/skills/cbp-ship-main/SKILL.md

@@ -0,0 +1,65 @@
+---
+scope: org-shared
+name: cbp-ship-main
+description: Ship feat branch to production branch via PR — thin wrapper around `codebyplan ship`
+model: sonnet
+effort: high
+---
+
+# Ship Main Command
+
+Compose a PR body from checkpoint context, then delegate all git/gh mechanics to `codebyplan ship`.
+
+## Instructions
+
+### Step 1: Read Checkpoint Context
+
+Use MCP `get_current_task` (repo_id) to get the active checkpoint. Collect `checkpoint.title`, completed task titles (`get_tasks(checkpoint_id)` filtered to `status === 'completed'`), and key decisions from `checkpoint.context.decisions[]`.
+
+### Step 2: Compose PR Body
+
+Write to `/tmp/cbp-ship-main-body.md`:
+
+```markdown
+## Summary
+
+{checkpoint.title}
+
+## Tasks Completed
+
+{bullet list of completed task titles}
+
+## Key Changes
+
+{2–5 bullets from decisions or task requirements}
+
+## Test Plan
+
+- All rounds passed testing-qa
+- /cbp-checkpoint-check passed
+```
+
+### Step 3: Invoke `codebyplan ship`
+
+```bash
+# DRY_RUN is non-empty when the skill was invoked with a dry-run arg; otherwise empty.
+codebyplan ship --body-file /tmp/cbp-ship-main-body.md --json${DRY_RUN:+ --dry-run}
+```
+
+Pass `--dry-run` through if the skill was invoked with a dry-run arg.
+
+### Step 4: Report
+
+Parse JSON from Step 3. Report `pr_url`, `merge_commit`, `branch_deleted`. If `checks_failed: true`, surface `checks_failure_reason` and stop.
+
+## Key Rules
+
+- **Read branch names from config** — never hardcode "main"
+- **Never force push** — always via PR (enforced by `codebyplan ship`)
+- **Pass --dry-run through** when skill is invoked with dry-run arg
+
+## Integration
+
+- **Called by**: `/cbp-checkpoint-end`
+- **Delegates to**: `codebyplan ship` CLI
+- **Reads**: MCP `get_current_task`, `get_tasks`

package/templates/skills/cbp-supabase-branch-check/SKILL.md

@@ -0,0 +1,337 @@
+---
+scope: org-shared
+name: cbp-supabase-branch-check
+description: Gate skill called by /cbp-ship-main (pre-merge) to verify the Supabase preview branch health check is green before allowing a PR to be merged; skips when no DB-path changes are detected.
+argument-hint: "[--mode pre_pr_create|pre_merge] [--target integration|production]"
+allowed-tools: Bash(git *), Bash(gh *), Bash(jq *), Bash(supabase *), Bash(sleep *), Bash(echo *), Read, mcp__supabase__list_branches, mcp__supabase__get_logs
+model: sonnet
+effort: xhigh
+---
+
+# Supabase Branch Check
+
+Gate skill invoked by `/cbp-ship-main` to verify the Supabase preview branch GitHub check
+is green before allowing a PR to be merged. When no DB-path changes exist on the current
+branch, the skill emits `skipped` immediately — no polling occurs.
+
+## Arguments
+
+Inspect `$ARGUMENTS`:
+
+- `--mode pre_pr_create` — soft mode; `pending_pr` is a pass-through (PR not open yet). Default target: `integration`.
+- `--mode pre_merge` — hard mode (default); `pending_pr` or `blocked` refuse merge. Default target: auto-detect from PR base.
+- `--target integration|production` — override target branch lookup.
+
+## Return Contract
+
+Every exit path emits a fenced JSON block in chat output so callers can parse deterministically:
+
+```json
+{ "status": "passed|skipped|pending_pr|blocked",
+  "reason": "human-readable string",
+  "failed_step": "clone|pull|health|configure|migrate|seed|deploy",
+  "log_excerpt": "verbatim first ~500 chars" }
+```
+
+`failed_step` and `log_excerpt` are only included on `blocked` triggered by a DAG failure.
+
+## Step 0 — Parse Arguments
+
+```bash
+MODE="pre_merge"
+TARGET=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --mode) MODE="$2"; shift 2 ;;
+    --target) TARGET="$2"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+```
+
+Validate `MODE`: must be `pre_pr_create` or `pre_merge`. If invalid, stop with error:
+
+```
+Invalid --mode value: <value>. Valid values: pre_pr_create, pre_merge.
+```
+
+Infer `TARGET` when absent:
+- `pre_pr_create` → `integration`
+- `pre_merge` → detect via `gh pr view --json baseRefName --jq '.baseRefName'`; fallback to `integration` if no PR is open.
+
+## Step 1 — Read DB Paths Config
+
+Read `.codebyplan.json` to obtain the configured DB path globs:
+
+```bash
+DB_PATHS=$(jq -r '.shipment.surfaces.supabase.db_paths[]? // empty' .codebyplan.json 2>/dev/null)
+```
+
+If `DB_PATHS` is empty, fall back to defaults:
+
+```bash
+if [ -z "$DB_PATHS" ]; then
+  DB_PATHS=$(printf '%s\n' 'supabase/**' 'apps/backend/**' 'packages/**/db/**')
+fi
+```
+
+Store each pattern as a separate entry for matching in Step 2.
+
+## Step 2 — Detect DB-Path Changes
+
+Resolve the BASE branch from `TARGET`. Read `.codebyplan.json`:
+
+```bash
+INTEGRATION=$(jq -r '.branch_config.integration // "development"' .codebyplan.json)
+PRODUCTION=$(jq -r '.branch_config.production // "main"' .codebyplan.json)
+```
+
+Set `BASE`:
+- `TARGET=integration` → `BASE="$INTEGRATION"`
+- `TARGET=production` → `BASE="$PRODUCTION"`
+
+Run git diff to list changed files:
+
+```bash
+git fetch origin "$BASE" 2>/dev/null
+CHANGED_FILES=$(git diff --name-only "origin/$BASE"...HEAD)
+```
+
+```bash
+if [ -z "$CHANGED_FILES" ]; then
+  # No files changed at all — soft-skip
+  emit { "status": "skipped", "reason": "No file changes against $BASE" } and exit
+fi
+```
+
+Match each changed file against each DB path pattern using bash globstar:
+
+```bash
+shopt -s globstar
+MATCHED=false
+while IFS= read -r file; do
+  for pattern in $DB_PATHS; do
+    # bash 4+ supports ** in [[ ]] glob matching
+    if [[ "$file" == $pattern ]]; then
+      MATCHED=true
+      break 2
+    fi
+  done
+done <<< "$CHANGED_FILES"
+```
+
+If `MATCHED=false`, emit and exit:
+
+```json
+{
+  "status": "skipped",
+  "reason": "No DB-path changes detected against <BASE>"
+}
+```
+
+## Step 3 — Resolve project_ref
+
+```bash
+BRANCH=$(git branch --show-current)
+```
+
+**MCP path (preferred)**: Call `mcp__supabase__list_branches`. Filter the returned array for the
+entry where the git-branch field matches `$BRANCH`. The field name varies by API version —
+check `git_branch`, `branch_name`, or `ref` at runtime; use the first non-null value.
+Extract `project_ref` from the matched entry.
+
+**CLI fallback** (when MCP unavailable):
+
+```bash
+if ! command -v supabase >/dev/null 2>&1; then
+  # CLI not installed — explicit blocked status (avoids misleading "no preview")
+  emit { "status": "blocked", "reason": "supabase CLI not installed — run: npm i -g supabase" } and exit
+fi
+supabase --experimental branches get "$BRANCH" -o env \
+  | grep 'SUPABASE_PROJECT_REF' | cut -d= -f2
+```
+
+Store as `PROJECT_REF`.
+
+## Step 4 — Handle Missing project_ref
+
+If `PROJECT_REF` is empty after Step 3:
+
+- `MODE=pre_pr_create`:
+
+```json
+{
+  "status": "pending_pr",
+  "reason": "Push commit + open PR — Supabase creates the preview branch when the PR opens"
+}
+```
+
+Exit (soft pass — caller proceeds to create the PR).
+
+- `MODE=pre_merge`:
+
+```json
+{
+  "status": "blocked",
+  "reason": "No Supabase preview branch found for <BRANCH>. Push commit and open a PR first."
+}
+```
+
+Exit (hard block).
+
+## Step 5 — PR Existence Check
+
+Verify an open PR exists for this branch:
+
+```bash
+PR_JSON=$(gh pr view --json number,baseRefName 2>/dev/null)
+PR_NUMBER=$(echo "$PR_JSON" | jq -r '.number // empty')
+```
+
+```bash
+if [ -z "$PR_NUMBER" ] && [ "$MODE" = "pre_pr_create" ]; then
+  # No PR yet — Supabase will create the preview branch when the PR opens
+  emit { "status": "pending_pr", "reason": "No PR open yet for branch <BRANCH>; open a PR and re-run" } and exit
+fi
+```
+
+If `PR_NUMBER` is empty AND `MODE=pre_merge`:
+
+```json
+{
+  "status": "blocked",
+  "reason": "No PR open for branch <BRANCH>; cannot verify Supabase Preview check"
+}
+```
+
+Exit. (With the pre_pr_create guard above, pre_merge is the only mode that reaches this point with an empty PR_NUMBER.)
+
+## Step 6 — Bounded Poll: Supabase Preview Check
+
+Poll the GitHub PR checks for the `Supabase Preview` status check. Cap at 20 iterations
+with 15 seconds between each (5-minute ceiling total).
+
+```bash
+FAILED=false
+
+for i in $(seq 1 20); do
+  # Primary: gh ≥2.32 (Jul 2023) supports `bucket` (pass|fail|pending|skipping|cancel).
+  # Fallback: older gh omits bucket — request name,state and let jq derive bucket from state.
+  CHECK_JSON=$(gh pr checks "$PR_NUMBER" --json name,bucket,state 2>/dev/null \
+    || gh pr checks "$PR_NUMBER" --json name,state 2>/dev/null)
+
+  BUCKET=$(echo "$CHECK_JSON" \
+    | jq -r '.[] | select(.name == "Supabase Preview") |
+        (.bucket //
+         (.state |
+           if . == "SUCCESS" then "pass"
+           elif . == "SKIPPED" or . == "NEUTRAL" then "skipping"
+           elif . == "FAILURE" or . == "ERROR" or . == "CANCELLED"
+                or . == "STALE" or . == "ACTION_REQUIRED"
+                or . == "TIMED_OUT" then "fail"
+           else "pending" end))
+        // empty')
+
+  case "$BUCKET" in
+    pass)
+      break
+      ;;
+    skipping)
+      break
+      ;;
+    pending)
+      echo "poll $i/20: Supabase Preview bucket=$BUCKET, sleeping 15s"
+      sleep 15
+      ;;
+    fail)
+      FAILED=true
+      break
+      ;;
+    cancel)
+      FAILED=true
+      break
+      ;;
+    "")
+      echo "poll $i/20: Supabase Preview not yet in check list, sleeping 15s"
+      sleep 15
+      ;;
+  esac
+done
+```
+
+After the loop, dispatch on the final `$BUCKET` and `$FAILED` state:
+
+```bash
+if [ "$FAILED" = "true" ]; then
+  : # proceed to Step 7 (failure path)
+elif [ "$BUCKET" = "pass" ] || [ "$BUCKET" = "skipping" ]; then
+  : # proceed to Step 8 (success path — pass/skipping branches differ below)
+else
+  # Loop exhausted with $BUCKET still "pending" or empty — emit timeout.
+  if [ -n "$BUCKET" ]; then
+    REASON="Supabase Preview still $BUCKET after 5 min (20 polls)"
+  else
+    REASON="Supabase Preview not found in check list after 5 min (20 polls)"
+  fi
+fi
+```
+
+Timeout emit (when loop exhausted):
+
+```json
+{
+  "status": "blocked",
+  "reason": "<REASON computed above>"
+}
+```
+
+## Step 7 — Failure: Fetch Logs and Map DAG Step
+
+Read `reference/dag-steps.md` for DAG step → service mapping. Attempt to read the failed
+step name from the check output (`description` or `name` field).
+
+Query logs in priority order until a non-empty result is obtained:
+1. `mcp__supabase__get_logs(project_ref=PROJECT_REF, service="postgres")` — migrate/seed/health
+2. `mcp__supabase__get_logs(project_ref=PROJECT_REF, service="api")` — clone/pull/configure
+3. `mcp__supabase__get_logs(project_ref=PROJECT_REF, service="edge-function")` — deploy only
+
+Cap excerpt at first 500 chars of the first non-empty result.
+
+```json
+{
+  "status": "blocked",
+  "reason": "<human-readable description of the failure>",
+  "failed_step": "<clone|pull|health|configure|migrate|seed|deploy>",
+  "log_excerpt": "<verbatim first ~500 chars of logs>"
+}
+```
+
+## Step 8 — Success
+
+Two sub-cases distinguished by `$BUCKET`:
+
+When `$BUCKET = pass` (check ran and passed):
+
+```json
+{
+  "status": "passed",
+  "reason": "Supabase Preview check green for branch <BRANCH>"
+}
+```
+
+When `$BUCKET = skipping` (check skipped at CI level — e.g. Supabase decided no preview was needed despite this skill's earlier DB-path check passing):
+
+```json
+{
+  "status": "passed",
+  "reason": "Supabase Preview check skipped at CI for branch <BRANCH>"
+}
+```
+
+Both emit `status: passed` so callers proceed; the `reason` differs for traceability.
+
+## Integration
+
+**Callers**: `/cbp-ship-main` invokes this skill pre-merge (mode=`pre_merge`, target=`production`, no override).
+**Tools used**: `mcp__supabase__list_branches` for project_ref resolution; `mcp__supabase__get_logs` for failure diagnostics; `gh pr checks` for status polling; `supabase --experimental branches get` as CLI fallback.

package/templates/skills/cbp-supabase-branch-check/reference/dag-steps.md

@@ -0,0 +1,29 @@
+---
+scope: org-shared
+---
+
+# DAG Steps — Supabase Preview Branch
+
+Reference for cbp-supabase-branch-check Step 7. Maps each Supabase branching DAG step
+to its likely root cause, recommended user action, and the get_logs service to query.
+
+## Mapping Table
+
+| DAG Step   | Likely Root Cause                                      | User Action                                                        | get_logs service |
+|------------|--------------------------------------------------------|--------------------------------------------------------------------|------------------|
+| clone      | Repository not accessible to Supabase app              | Re-authorize GitHub app in Supabase dashboard                      | api              |
+| pull       | Branch not pushed to remote                            | git push origin <branch>                                           | api              |
+| health     | Preview DB failed to provision                         | Check Supabase status page; retry via dashboard                    | postgres         |
+| configure  | supabase/config.toml parse error or missing block      | Check config.toml syntax; verify [remotes.*] block                 | api              |
+| migrate    | Migration SQL error (syntax, constraint)               | Fix migration file, re-push branch                                 | postgres         |
+| seed       | seed.sql error or timeout                              | Check supabase/seed.sql; reduce seed size                          | postgres         |
+| deploy     | Edge function deploy failure                           | Check edge function logs; verify function syntax                   | edge-function    |
+
+## Service Selection Logic
+
+When the DAG step name is not visible in the log, query in this order:
+1. `postgres` — covers migration, seed, and health failures (most common)
+2. `api` — covers clone, pull, configure failures
+3. `edge-function` — only for deploy step failures
+
+Provide the first non-empty log result to the user as the `log_excerpt`.