@launchsecure/launch-kit 0.0.26 → 0.0.28

package/scaffolds/ls-marketplace/plugins/ls/commands/standup.md

@@ -0,0 +1,177 @@
+---
+description: Draft a daily standup from work done since the last push, group themes using launch-chart, show the draft, and post to LaunchSecure Comm Hub as a daily_update after explicit confirmation.
+---
+
+# Standup
+
+Generates a daily-update comment for the LaunchSecure Comm Hub. Pulls commits since the last push (with fallbacks), groups them by codebase layer/module using `launch-chart`, drafts a summary in the project's house style, shows it to the user, and posts only after the user confirms. Never posts without explicit "yes".
+
+## Preflight
+
+1. Verify `.launch-secure.cred.config` exists at the repo root. If missing, abort and tell the user to run `npx launch-kit init` first — without the cred file the `launch-secure` MCP cannot authenticate, so we cannot read prior standups or post the new one.
+2. Verify we are inside a git repo (`git rev-parse --git-dir`). If not, abort with a clear message.
+3. Record the current branch (`git rev-parse --abbrev-ref HEAD`).
+4. Detect whether `launch-chart` is wired by calling `mcp__launch-chart__detect_project_stack`. If the call fails or returns nothing, fall back to git-only grouping (note this in the final summary).
+
+## Gather
+
+Pull data from layered sources, in this order:
+
+### 1. Determine the window
+
+- **Primary**: `git log --reverse --pretty=format:'%h%x09%an%x09%ae%x09%s%n%b%n%x00' @{push}..HEAD`. The `@{push}` revspec resolves to where this branch was last pushed; the diff is commits ahead of upstream.
+- **Fallback 1**: if the primary returns empty OR `@{push}` errors with `unknown revision`, query the `launch-secure` MCP via `communication_read({ tag: "daily_update", limit: 1 })`. Take the most recent comment's `createdAt`; gather commits since then via `git log --since="<that timestamp>"`.
+- **Fallback 2**: if no prior `daily_update` exists either, use `git log --since="24 hours ago"`.
+
+Tell the user which window was used in one short line ("Using commits since last push (12 commits)" or "No commits since last push — falling back to commits since 2026-05-20 14:01 (last standup)").
+
+### 2. Collect change context
+
+- `git diff --stat @{push}..HEAD` (or whichever window was chosen) — file paths + line counts. Drives theme grouping in the next step.
+- `git log --pretty=format:'%h %s' <window>` — short subject lines for quick scan.
+- Branch names + PR references in commit messages (look for `#<digits>`, `LS-<id>`, branch slugs like `fix/foo-bar`). These are work-item handles.
+
+### 3. Group by layer/module using launch-chart
+
+This is the chart's job — do **not** group by file path string-matching. For each changed file (deduped from the diff stat):
+
+- Call `mcp__launch-chart__read_graph({ search: "<file basename>", layer: "<best guess: ui|api|db|static>" })` to resolve the file to a graph node, OR
+- Call `mcp__launch-chart__read_graph({ node_id: "<full path>" })` if the file path matches a known node id format
+
+From the resolved nodes, pull each node's `module` and `layer` fields. Group commits/files into themes by `module` first, then by `layer` when `module` is missing. Common LS modules: `auth`, `pda`, `pda-guides`, `pda-shell`, `radar`, `chart`, `orbit`, `recall`, `comms`, `board`, `webhooks`, `feedback`, `briefs`, `mcp`, etc.
+
+If a file doesn't resolve in the chart (new file, non-TS, config), bucket it under "Misc" or by directory (`scripts/`, `docs/`, `.github/`).
+
+### 4. Audit pass (optional, skip if it slows things down)
+
+Call `mcp__launch-chart__audit_layer({ layer: "all" })` to surface any drift introduced today (schema_drift, unprotected_routes, dead_screens, hardcoded_values). If the audit reports new issues that didn't exist before (best-effort — compare against the prior standup's audit if possible, otherwise just report current state), flag them in the closing `----` block.
+
+### 5. Blast radius for the biggest changes (deploy-safety signal)
+
+For the top-3 files by lines-changed in `git diff --stat`, call `mcp__launch-chart__blast_points({ node_id: "<file>", hops: 2 })`. If any of them has a blast radius of >10 dependent nodes, note it as a deploy-risk signal in the `----` block ("touched X which has 24 downstream consumers — review before deploy").
+
+### 6. Work-item linkage
+
+For each work-item handle found in commit messages, call `mcp__launch-secure__work_items_list` (or `work_item_get` if you have an ID) to pull title + status. If any work items were closed today (status changed to DONE/COMPLETED), call them out in the closing block.
+
+### 7. Release detection
+
+A commit qualifies the post for the `release` tag if ANY of the following are true:
+- `package.json` `version` field changed in `git diff @{push}..HEAD -- package.json`
+- A migration file under `prisma/migrations/` was added or `prisma/schema.prisma` changed
+- A deploy/publish was mentioned in commit subjects (regex: `\b(publish|release|deploy|bump)\b`)
+- A new bin or export was added to a package's `package.json`
+
+If any are true, set `addReleaseTag = true`. Otherwise `false`.
+
+## Draft
+
+Produce the standup in the **exact** house format. This is the format Prajyot uses for human-written daily updates (verified against the May 18, 19, 20 posts in the Comm Hub):
+
+```
+Hey @everyone
+
+Pushed <N> commits to <branch> today. Highlights:
+
+→ <Theme 1>
+- <outcome bullet, not a commit message>
+- <outcome bullet>
+
+→ <Theme 2>
+- <outcome bullet>
+
+→ <Theme N>
+- <outcome bullet>
+
+----
+
+<one-line PSA or deploy-safety note. Examples: "TS clean, no schema/migration changes, safe to deploy." or "Includes prisma migration <name> — run migrate-with-backup.sh before deploy.">
+
+Thanks
+```
+
+**Strict format rules:**
+
+- `Hey @everyone` — exactly this. Not "Hey team", not "Hi everyone". Single line, blank line after.
+- `Pushed N commits to <branch> today. Highlights:` — replace `<branch>` with the actual branch from preflight. If the window was a fallback (not "since last push"), say "Drafted N commits' worth of work on <branch> today. Highlights:" instead — be honest about the window.
+- `→ <Theme>` — right-arrow + space + theme name. Theme names come from chart's `module` grouping (e.g. "→ Radar", "→ Webhooks", "→ Chart / Freshness"). Capitalize the first letter.
+- `- <bullet>` — plain hyphen + space. Bullets are **outcomes**, not commit messages. Translate "feat(radar): add transcript view" into "Structured transcript view with overlay reply drawer". Drop scope prefixes and verb tense.
+- Blank line between themes.
+- `----` — four hyphens, on its own line, blank line above and below.
+- The closing block: one short line is fine. Don't pad.
+- `Thanks` — exact word, no comma, no name signature (the post's author is attached automatically).
+
+**Constraints:**
+
+- Plain text only. No `**bold**`, no `*italic*`, no backticks, no `# headers`, no markdown link syntax. The Comm Hub renders as plain text.
+- Aim for ≤ 350 words total. Standups are skim-able; trim aggressively.
+- Top 3–6 themes is the sweet spot. If you have 20 commits in 12 different modules, collapse the small ones into a "→ Misc" theme.
+- Bullets should be **outcome-shaped**: what landed in the product, not what the diff did. "Multi-select EventTypesPicker on subscription forms" beats "modified components/webhooks/EventTypesPicker.tsx".
+- Mention work-item closures and any deploy-affecting changes (migrations, env var changes, breaking API changes) in the closing block.
+
+## Confirm
+
+Show the draft to the user verbatim in a code-fenced block (so they see plain-text formatting as-is), then ask **exactly**:
+
+> "Post this as a daily_update to LS Comm Hub? Reply `yes` to post, `edit` to revise, or `cancel` to abort."
+
+Responses:
+
+- **`yes`, `y`, `ok`, `post it`** — proceed to duplicate check + post.
+- **`edit`, `change <thing>`, free-form revisions** — apply the edits, regenerate the draft, re-show, re-ask.
+- **`cancel`, `no`, `nope`** — abort. Don't post. Don't keep partial state.
+
+Anything ambiguous → treat as "edit, what would you like changed?".
+
+## Duplicate check
+
+Before posting, call `mcp__launch-secure__communication_read({ tag: "daily_update", limit: 5 })`. If any returned comment has:
+- `resourceType: "comment"` (not `"daily_update"` — that's bot-only, distinct stream)
+- `author.email` matches the current user's email (from `git config user.email`)
+- `createdAt` within the last 12 hours
+
+…then a manual daily_update already exists from today. Offer:
+
+> "A daily_update already exists from you today (posted at <time>, <preview-50-chars>). Choose: `replace` to update it (communication_update), `append` to post another, `cancel` to stop."
+
+- **replace** → call `mcp__launch-secure__communication_update({ id: "<existing-id>", content: <new-draft> })`. Preserve tags.
+- **append** → proceed to post.
+- **cancel** → abort.
+
+## Post
+
+Call `mcp__launch-secure__communication_write`:
+
+```
+{
+  resourceType: "comment",
+  content: "<the final draft, plain text>",
+  tags: addReleaseTag ? ["daily_update", "release"] : ["daily_update"]
+}
+```
+
+`org_slug` and `project_slug` are auto-supplied from the cred config via the MCP's headersHelper — do NOT pass them yourself.
+
+On success: report the comment ID and a friendly "posted to LS Comm Hub" line. If the response includes a URL field, surface it.
+
+On failure: surface the error verbatim. Don't retry automatically — auth or schema errors deserve human attention. The draft is preserved in chat so the user can retry manually.
+
+## Tag handling
+
+Before adding any tag, you may verify it exists via `mcp__launch-secure__tags_list`. The `daily_update` and `release` tags are standard in LS projects; if either is missing, the post will still succeed but the tag won't attach. Surface this as a warning, not a blocker.
+
+## Idempotency
+
+Re-running `/ls:standup`:
+- Always re-pulls the window fresh. No cached state.
+- Duplicate check handles same-day reposts.
+- The draft is never written to disk — only shown in chat. User can copy it manually if they cancel.
+
+## Notes for the assistant
+
+- Use `launch-chart` for grouping, not grep/glob. The whole point is producing themes that match how the codebase is organized, not how files are named.
+- The user's preference is short, terse standups (verified style across May 18→20 posts). Default to under-rather-than-over.
+- "Outcome bullet, not commit message" is the single most important transform. A standup full of "feat(x): add y" reads like a changelog, not a status.
+- Never assume `release` tag without evidence (see Release detection above). False positives confuse downstream consumers.
+- Don't ask the user clarifying questions before drafting — produce a first cut, then iterate. The draft is cheap; the conversation isn't.
+- If `launch-chart` is unavailable (no `.launchchart.json`, MCP not responding), fall back to grouping by top-level path segment (`src/app/api/` → "API", `src/client/components/board/` → "Board", etc.) and note "chart unavailable, grouped by path" in chat (not in the post).

package/scaffolds/migrate-safety/.github/workflows/backup-on-migration.yml

@@ -0,0 +1,72 @@
+name: Backup prod DB before migration deploys
+
+# Triggers a logical pg_dump of prod whenever a migration file lands on master
+# or implementation. Backup is uploaded as a workflow artifact (90-day retention)
+# tied to the commit SHA — see docs/migrations-runbook.md for restore steps.
+#
+# Required secrets (configure under repo Settings → Secrets and variables → Actions):
+#   PROD_DATABASE_URL  — full DATABASE_URL for the production DB.
+#                        Treat this as production credential — anyone who can
+#                        download the artifact effectively has prod data.
+#
+# Required permissions: this workflow only reads from the DB and writes an
+# artifact; it does not push code, deploy, or modify anything.
+
+on:
+  push:
+    branches: [master, implementation]
+    paths:
+      - 'prisma/migrations/**'
+      - 'prisma/schema.prisma'
+  workflow_dispatch: # allow manual runs for ad-hoc snapshots
+
+permissions:
+  contents: read
+
+jobs:
+  backup:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Run wrapper in backup-only mode
+        env:
+          # The same env-var contract used for local — only the destination differs.
+          DATABASE_URL: ${{ secrets.PROD_DATABASE_URL }}
+          BACKUP_DIR: artifacts
+          # Force docker so the wrapper auto-detects the server's major version
+          # and pulls the matching postgres:<major> image. Avoids hardcoding a
+          # client version that drifts when prod Postgres is upgraded.
+          # ubuntu-latest runners ship with docker pre-installed.
+          PG_DUMP_VIA_DOCKER: '1'
+        run: |
+          if [[ -z "$DATABASE_URL" ]]; then
+            echo "::error::PROD_DATABASE_URL secret is not configured."
+            echo "Set it under repo Settings → Secrets and variables → Actions."
+            exit 1
+          fi
+          bash scripts/migrate-with-backup.sh backup-only
+
+      - name: Upload dump as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: prod-db-backup-${{ github.sha }}
+          path: artifacts/*.sql.gz
+          retention-days: 90
+          if-no-files-found: error
+
+      - name: Summary
+        run: |
+          echo "### Backup complete" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Triggered by: \`${{ github.event_name }}\` on \`${{ github.ref_name }}\`" >> $GITHUB_STEP_SUMMARY
+          echo "Commit: \`${{ github.sha }}\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Download via:" >> $GITHUB_STEP_SUMMARY
+          echo '```bash' >> $GITHUB_STEP_SUMMARY
+          echo "gh run download ${{ github.run_id }} -n prod-db-backup-${{ github.sha }}" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Restore steps: see [docs/migrations-runbook.md](../blob/${{ github.sha }}/docs/migrations-runbook.md)." >> $GITHUB_STEP_SUMMARY

package/scaffolds/migrate-safety/docs/migrations-runbook.md

@@ -0,0 +1,172 @@
+# Migrations runbook
+
+Operational reference for the three-layer migration safety system. Read this before running a migration in prod, and again when something has gone wrong.
+
+## The three layers (recap)
+
+| Layer | What | Where defined |
+|---|---|---|
+| 1 — Process | Expand-and-contract: never combine "add + backfill + drop" in one migration. Two PRs, two deploys. | `CLAUDE.md` |
+| 2 — Tooling | `scripts/migrate-with-backup.sh` — pg_dump before every `prisma migrate`, abort if dump fails. | `scripts/migrate-with-backup.sh` |
+| 3 — In-migration SQL | Pre-flight count + abort-on-orphan + sidecar backup table before any column drop. | `CLAUDE.md` |
+
+Recovery never depends on a single layer. PITR (if your provider has it) is a fourth, continuous layer underneath.
+
+## Routine: running a migration
+
+### Local (against `.env.testing` or `.env`)
+
+```bash
+# Always use these — they wrap pg_dump around prisma migrate.
+npm run db:migrate                  # = prisma migrate dev (creates a new migration)
+npm run db:migrate:deploy           # = prisma migrate deploy (applies pending migrations)
+npm run db:backup                   # dump only, no migration (manual snapshot)
+```
+
+Backups land in `.backups/pre-migrate-<mode>-<YYYYMMDD-HHMMSS>-<git-sha>.sql.gz`. The directory is gitignored. Prune old ones manually when convenient.
+
+If your local `pg_dump` is older than the server, the wrapper auto-falls-back to a Docker container with `postgres:16`. Override the image if your server is on a different major:
+
+```bash
+PG_DUMP_DOCKER_IMAGE=postgres:15 PG_DUMP_VIA_DOCKER=1 npm run db:backup
+```
+
+### Production (Vercel build)
+
+The Vercel `build` script still runs `prisma migrate deploy` directly — the *prod backup* is decoupled from the Vercel build and runs on GitHub Actions instead (see `.github/workflows/backup-on-migration.yml`). Whenever a commit on `master` or `implementation` touches `prisma/migrations/**` or `prisma/schema.prisma`, the workflow runs the same wrapper in `backup-only` mode against `PROD_DATABASE_URL` and uploads the dump as a GHA artifact.
+
+**One-time setup before the workflow can run**:
+
+1. Repo → Settings → Secrets and variables → Actions → "New repository secret"
+2. Name: `PROD_DATABASE_URL`. Value: full Postgres URL of prod (with credentials).
+3. Confirm the workflow file is on `master`. The first migration commit afterward will trigger it.
+
+## Recovery
+
+### Find the right backup
+
+**Local backups** — listed by timestamp + commit SHA:
+
+```bash
+ls -lt .backups/
+```
+
+**Prod backups (GHA artifacts)**:
+
+- Web UI: repo → **Actions** tab → "Backup prod DB before migration deploys" workflow → click the run for the relevant commit → scroll to "Artifacts" at the bottom → download the `.zip`.
+- CLI:
+  ```bash
+  gh run list --workflow=backup-on-migration.yml --limit 10
+  gh run download <run-id> -n prod-db-backup-<commit-sha>
+  ```
+
+GHA artifacts are retained for 90 days by default (configurable in the workflow file).
+
+### Restore commands
+
+The dump format is identical regardless of where it came from (local or GHA), so the restore commands work for both. Decompress with `gunzip -c` (portable; macOS `zcat` does NOT decompress `.gz`).
+
+**1. Inspect a dump without restoring:**
+
+```bash
+gunzip -c .backups/pre-migrate-deploy-<ts>-<sha>.sql.gz | head -50
+gunzip -c .backups/pre-migrate-deploy-<ts>-<sha>.sql.gz | grep -E '^(CREATE TABLE|INSERT INTO "Project")' | head
+```
+
+**2. Restore to a fresh scratch database (for forensics, dry-run, or recovering a specific row):**
+
+```bash
+# Create a scratch DB (psql must point at a server you control; do NOT do this against prod)
+createdb scratch_restore
+# Or via psql: psql -c 'CREATE DATABASE scratch_restore' "$ADMIN_DB_URL"
+
+gunzip -c .backups/pre-migrate-deploy-<ts>-<sha>.sql.gz \
+  | psql "postgresql://USER:PASS@HOST:PORT/scratch_restore"
+```
+
+Now you have an exact copy of the pre-migration state. Inspect, copy specific rows back to prod, or run the migration against the scratch DB to verify what *would* happen.
+
+**3. Full prod rollback (last resort — see provider section below first):**
+
+```bash
+# DESTRUCTIVE — drops the existing schema and replaces it with the dumped contents.
+# Only do this if PITR is unavailable AND you've decided a full rollback is the right call.
+# The dump uses --no-owner --no-privileges, so Postgres roles are NOT modified.
+
+# 1. Take a current dump first (in case rollback itself goes wrong)
+DATABASE_URL="$PROD_DATABASE_URL" npm run db:backup
+
+# 2. Drop and recreate public schema
+psql "$PROD_DATABASE_URL" -c 'DROP SCHEMA public CASCADE; CREATE SCHEMA public;'
+
+# 3. Restore from the pre-migration dump
+gunzip -c .backups/pre-migrate-deploy-<ts>-<sha>.sql.gz | psql "$PROD_DATABASE_URL"
+
+# 4. Re-run prisma migrate so the migrations table reflects current state
+DATABASE_URL="$PROD_DATABASE_URL" npx prisma migrate resolve --applied <last-good-migration>
+```
+
+### Provider-specific recovery (preferred over manual restore when available)
+
+| Provider | Recovery feature | Notes |
+|---|---|---|
+| Neon | Branch from PITR | Console → Branches → "Create branch from a previous state" → pick a timestamp before the bad migration. Update `DATABASE_URL` to the new branch. Free tier: 7-day retention. |
+| Vercel Postgres | Same as Neon (it's Neon) | Use the Vercel dashboard or Neon console. |
+| Supabase | Daily snapshots (paid tiers) | Dashboard → Database → Backups. |
+| RDS / Aurora | Automated snapshots + PITR | AWS console. PITR up to backup retention period. |
+| Self-hosted | Whatever you set up | Hopefully `pg_basebackup` + WAL archiving. |
+
+**Rule of thumb**: provider PITR > GHA artifact > local `.backups/`. Try them in that order — PITR is closest to "the exact moment before things broke," GHA artifacts are the moment before deploy, local backups are whoever ran the last migration on their laptop.
+
+## Dry-running a migration before merging
+
+Before merging a destructive migration PR, restore a fresh GHA artifact (or a `pg_dump` you took manually against prod) into a scratch DB and run the migration there. Check row counts before/after. If the wrapper aborts on orphan check, the migration is broken — fix the SQL.
+
+```bash
+# Pull most recent prod backup
+gh run download $(gh run list --workflow=backup-on-migration.yml --limit 1 --json databaseId -q '.[0].databaseId') \
+  -n prod-db-backup-<sha> -D /tmp/prod-snapshot
+
+# Spin up a scratch DB and restore
+createdb migration_dryrun
+gunzip -c /tmp/prod-snapshot/*.sql.gz | psql "postgresql://localhost/migration_dryrun"
+
+# Apply the pending migration
+DATABASE_URL="postgresql://localhost/migration_dryrun" \
+  bash scripts/migrate-with-backup.sh deploy
+
+# Spot-check: did the rows you expected get backfilled?
+psql "postgresql://localhost/migration_dryrun" -c 'SELECT count(*) FROM "Project" WHERE ...;'
+```
+
+If the dry-run looks right, merge. If it doesn't, fix the migration and try again.
+
+## Security
+
+**Treat dump files like prod credentials.** They contain:
+
+- Hashed passwords (still attackable offline)
+- OAuth tokens stored in `Integration.metadata` — these are live credentials for Vercel, GitHub, Neon, etc. Anyone with the dump can impersonate the integration.
+- User PII (emails, names, anything stored in user-facing tables)
+
+**Therefore:**
+
+- `.backups/` is gitignored and must stay that way. Never commit a `.sql.gz` from this directory.
+- GHA artifacts inherit the repo's access — only collaborators on the repo can download them. If you make the repo public or add an external collaborator, they get historical artifacts too. Audit before changing access.
+- When sharing a dump for debugging, scrub the sensitive tables first (`Integration`, `Account`, `Session`, anything with tokens). A quick scrub:
+  ```bash
+  gunzip -c backup.sql.gz | grep -v '^COPY public."Integration"' | gzip > backup-scrubbed.sql.gz
+  ```
+  (This is a blunt instrument — it drops the entire `Integration` COPY block. Inspect before sharing.)
+- Rotate any tokens that may have been exposed if a dump leaks. Vercel/GitHub/Neon integration tokens can all be revoked from their respective dashboards.
+
+## Adding support for a new DB engine
+
+Today the wrapper supports Postgres only. To add MySQL/MongoDB/etc.:
+
+1. Add a case branch in `scripts/migrate-with-backup.sh` matching the URL scheme (`mysql://`, `mongodb://`, etc.).
+2. Use the appropriate dump tool (`mysqldump`, `mongodump`).
+3. Update the sanity check to recognize the new dump format.
+4. Update this runbook with restore commands for the new engine.
+
+The orchestration logic (dump → validate → migrate, abort on dump failure) stays identical.