codebyplan 1.5.1 → 1.9.0

package/templates/skills/cbp-ship-configure/reference/expo-mobile.md

@@ -0,0 +1,204 @@
+# Configure: expo-mobile
+
+Walkthrough for first-time Expo + EAS + TestFlight setup.
+
+## Prerequisites
+
+- Apple Developer Program enrollment ($99/yr) — https://developer.apple.com/programs/enroll/
+- Google Play Developer account ($25 one-time, optional if Android-only later)
+- Expo account (free) — https://expo.dev/signup
+- App Store Connect record for the app (created in ASC dashboard)
+
+## Probe
+
+```bash
+which npx
+npx eas-cli --version || { echo "Will install eas-cli on first use"; }
+npx eas whoami || { echo "Run: npx eas login"; exit 1; }
+```
+
+## Setup walkthrough
+
+### Step 1/9: Verify Expo account + EAS access
+
+```bash
+npx eas whoami
+```
+
+If not logged in:
+
+```
+Run: npx eas login
+Use your expo.dev account credentials.
+```
+
+### Step 2/9: Initialize EAS project
+
+```bash
+cd "$APP_PATH"
+npx eas init
+```
+
+This creates `eas.json` skeleton + adds `expo.extra.eas.projectId` to `app.json`.
+
+### Step 3/9: Configure `app.json`
+
+Verify these fields are set:
+
+```json
+{
+  "expo": {
+    "name": "Your App",
+    "slug": "your-app",
+    "version": "1.0.0",
+    "ios": {
+      "bundleIdentifier": "com.yourcompany.yourapp",
+      "buildNumber": "1"
+    },
+    "android": {
+      "package": "com.yourcompany.yourapp",
+      "versionCode": 1
+    }
+  }
+}
+```
+
+The bundle ID and package name **must match** your App Store Connect / Play Console records.
+
+### Step 4/9: Configure `eas.json`
+
+Use the template at `${CLAUDE_PLUGIN_ROOT}/skills/ship/templates/eas.json`. Customize:
+
+```json
+{
+  "cli": { "version": ">= 5.0.0" },
+  "build": {
+    "development": {
+      "developmentClient": true,
+      "distribution": "internal"
+    },
+    "preview": {
+      "distribution": "internal",
+      "ios": { "simulator": false },
+      "channel": "preview",
+      "autoIncrement": "buildNumber"
+    },
+    "production": {
+      "channel": "production",
+      "autoIncrement": "buildNumber"
+    }
+  },
+  "submit": {
+    "production": {
+      "ios": {
+        "appleId": "<your apple id email>",
+        "ascAppId": "<from App Store Connect — App Information → Apple ID>",
+        "appleTeamId": "<from developer.apple.com → Membership>"
+      },
+      "android": {
+        "serviceAccountKeyPath": "./google-play-service-account.json",
+        "track": "internal"
+      }
+    }
+  }
+}
+```
+
+### Step 5/9: Apple Developer credentials
+
+The skill walks the user through these one at a time:
+
+#### 5a. App Store Connect API key
+
+```
+1. Go to https://appstoreconnect.apple.com/access/api
+2. Click 'Generate API Key' (or 'Add Key' if you have access)
+3. Name it 'EAS Build', role 'App Manager'
+4. Download the .p8 file (you can only download ONCE)
+5. Note the Key ID and Issuer ID
+
+Save the .p8 file to ~/private_keys/AuthKey_<KEYID>.p8
+Reply with the Key ID and Issuer ID when ready.
+```
+
+#### 5b. Sync credentials with EAS
+
+```bash
+cd "$APP_PATH"
+npx eas credentials
+```
+
+This is interactive. The skill instructs:
+
+```
+- Select platform: iOS
+- Select build profile: production
+- Select 'Distribution Certificate' → Set up new
+- Use the App Store Connect API key from step 5a
+- Select 'Provisioning Profile' → Set up new
+
+Reply 'done' when finished.
+```
+
+#### 5c. Same for Android (if shipping Android)
+
+```
+1. Generate Service Account: https://console.cloud.google.com/iam-admin/serviceaccounts
+2. Grant 'Service Account User' role on Play Console (Users & Permissions)
+3. Download JSON key, save as ./google-play-service-account.json
+4. Add path to .gitignore (NEVER commit)
+```
+
+### Step 6/9: Persist to `.codebyplan/shipment.json`
+
+```json
+{
+  "surfaces": {
+    "expo-mobile": {
+      "configured_at": "<now>",
+      "app_path": "apps/mobile",
+      "eas_project_id": "<from app.json>",
+      "ios_bundle_id": "com.yourcompany.yourapp",
+      "android_package": "com.yourcompany.yourapp",
+      "default_testflight_group": "internal",
+      "versioning": "auto-build-number"
+    }
+  }
+}
+```
+
+### Step 7/9: Test build (dev profile)
+
+Before committing the config, verify the credential setup with a dev build:
+
+```bash
+npx eas build --profile development --platform ios --non-interactive
+```
+
+This is fast (~10 min) and confirms the iOS credential chain works without uploading to TestFlight.
+
+If it fails, the skill walks the user through `npx eas credentials` audit again.
+
+### Step 8/9: Stage `eas.json` + `app.json`
+
+The user reviews the diff and commits these files. The skill does NOT commit on the user's behalf.
+
+### Step 9/9: Verify the surface
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/skills/ship/scripts/detect-surfaces.sh" --filter=expo-mobile | jq
+# Expect: configured: true
+```
+
+## Done
+
+Surface is ready. `/cbp-ship` will offer mobile shipment options at next checkpoint end.
+
+## Common setup issues
+
+| Symptom | Fix |
+|---|---|
+| `eas init` fails "user does not have access" | Add the user to the Expo organization: https://expo.dev/accounts/{org}/members |
+| `eas credentials` shows "Distribution Certificate is invalid" | Renew via Apple Developer; Apple revokes after team ID changes or expiry |
+| TestFlight build rejected with ITMS-90xxx | Common: missing `NSCalendarsUsageDescription` etc. in `app.json` `expo.ios.infoPlist` |
+| Bundle ID rejected | Already in use by another developer; pick a different bundle ID |

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

@@ -0,0 +1,165 @@
+# Configure: npm-package
+
+Walkthrough for first-time npm publish setup.
+
+> **Special case** — when the package being configured is `packages/codebyplan-package` (i.e., the `codebyplan` npm package that ships `scope: org-shared` skills/agents/hooks via its `claude` asset subcommand group), the parent SKILL.md "Special case: `codebyplan` asset-publish automation" section runs additional probes (npm whoami, npm publish auth) and scaffolds (`release-please-config.json`, `.release-please-manifest.json` at repo root) on top of the generic walkthrough below. See SKILL.md for the full extra flow. (CHK-132 consolidated the prior `@codebyplan/claude` package into `codebyplan`.)
+
+## Prerequisites
+
+- npm account (https://www.npmjs.com/signup) — free
+- 2FA enabled (mandatory for publish): npm web → Profile → 2FA Settings → "Authorization and writes"
+- For scoped packages (`@scope/pkg`): the scope owned by your account or org
+
+## Probe
+
+```bash
+which npm
+npm whoami || { echo "Run: npm login"; exit 1; }
+npm profile get tfa | grep -q "auth-and-writes" || { echo "Enable 2FA: npm profile enable-2fa auth-and-writes"; exit 1; }
+```
+
+## Setup walkthrough
+
+### Step 1/7: Pick the package
+
+If monorepo with multiple publishable packages, configure each separately. The skill detects which `package.json` files have `private: false` (or absent) and asks which to configure.
+
+### Step 2/7: Verify package.json metadata
+
+The skill checks each required field one at a time:
+
+```
+✓ name: @codebyplan/web-package
+✓ version: 0.1.0
+✗ description: missing — what does this package do?
+✓ keywords: [...]
+✗ repository: missing — public GH URL?
+✓ license: MIT
+✗ author: missing
+```
+
+For each missing/wrong field, the skill prompts and writes the answer.
+
+### Step 3/7: Verify entrypoints
+
+```bash
+cd "$PKG_PATH"
+MAIN=$(jq -r .main package.json)
+[ -f "$MAIN" ] || echo "WARN: main entry $MAIN missing — needs build first"
+
+# Better: exports map
+EXPORTS=$(jq -r '.exports."."' package.json)
+[ "$EXPORTS" != "null" ] || echo "Recommend adding exports map for ESM/CJS dual support"
+```
+
+If `exports` is missing, suggest:
+
+```json
+{
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "README.md", "LICENSE"]
+}
+```
+
+### Step 4/7: Run package validators
+
+```bash
+cd "$PKG_PATH"
+npm pack --dry-run     # what's in the tarball
+pnpm publint           # package.json lint
+pnpm attw --pack       # ESM/CJS resolution check
+```
+
+Surface any errors/warnings; offer to fix obvious ones (missing `files`, wrong `main`).
+
+### Step 5/7: Pick versioning mode
+
+```
+A) Manual — bump package.json version yourself before each release
+B) release-please — GH Action opens version-bump PRs based on conventional commits (recommended)
+C) changesets — manual changeset entries; aggregator PR (recommended for monorepos)
+```
+
+If B, scaffold:
+
+```bash
+cp ${CLAUDE_PLUGIN_ROOT}/skills/ship/templates/workflow-release-please.yml .github/workflows/release-please.yml
+cp ${CLAUDE_PLUGIN_ROOT}/skills/ship/templates/release-please-config.json release-please-config.json
+echo '{".":"<current version>"}' > .release-please-manifest.json
+```
+
+If C:
+
+```bash
+cd "$REPO_ROOT"
+pnpm add -Dw @changesets/cli
+npx changeset init
+cp ${CLAUDE_PLUGIN_ROOT}/skills/ship/templates/workflow-changesets.yml .github/workflows/changesets.yml
+```
+
+### Step 6/7: Pick publish mode
+
+```
+A) Local publish (manual OTP per release) — works immediately
+B) OIDC trusted publishing from GH Actions — no token, no leak risk (recommended for prod)
+```
+
+If B:
+
+1. https://www.npmjs.com/settings/{account}/trusted-publishers
+2. Add: `<owner>/<repo>` → workflow `.github/workflows/npm-publish.yml`, environment `release`
+3. Skill scaffolds:
+
+```bash
+cp ${CLAUDE_PLUGIN_ROOT}/skills/ship/templates/workflow-npm-publish.yml .github/workflows/npm-publish.yml
+```
+
+The workflow uses `permissions: id-token: write` and runs `npm publish --provenance --access public`.
+
+### Step 7/7: Persist + verify
+
+```json
+{
+  "surfaces": {
+    "npm-package": {
+      "configured_at": "<now>",
+      "packages/codebyplan-package": {
+        "package_name": "codebyplan",
+        "versioning": "release-please",
+        "publish_mode": "oidc",
+        "access": "public"
+      }
+    }
+  }
+}
+```
+
+Verify (no actual publish — just dry-run the publish command):
+
+```bash
+cd "$PKG_PATH"
+npm publish --dry-run
+# Inspect output for warnings; no upload happens
+```
+
+## Done
+
+Surface is ready. `/cbp-ship` will offer publish when version bumps.
+
+## Common setup issues
+
+| Symptom                                | Fix                                                                         |
+| -------------------------------------- | --------------------------------------------------------------------------- |
+| `npm publish` 402 (paid plan required) | Scoped public package needs `--access public` (default is private for orgs) |
+| 403 on first publish                   | Scope not owned by you; create org or use unscoped name                     |
+| `attw` reports "FalseESM"              | `package.json` `type: "module"` but exports point to .cjs files             |
+| Tarball missing TypeScript types       | Add `"types"` to `exports` map AND add `dist/**/*.d.ts` to `files`          |

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