@m-kopa/launchpad-cli 0.23.0

package/skills/launchpad-destroy/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: launchpad-destroy
+description: Tear down a Launchpad app end-to-end via `launchpad destroy` — Cloudflare Pages project, Access app, custom hostname, platform-repo TF entries, and the app repo (archive-renamed). Owner-only verb with a two-step destructive confirmation. Use when someone says "destroy this app", "/launchpad-destroy", "tear down `<slug>`", "delete the app", or asks to clean up a smoke-test / orphan / retired app.
+version: 0.23.0
+---
+
+<!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
+## Shell contract — read this first
+
+Every fenced `bash` block below MUST be sent to the `Bash` tool **verbatim**.
+Do not rewrite into PowerShell, cmd, zsh-isms, or "equivalent" forms.
+
+- macOS / Linux: the `Bash` tool runs system bash.
+- Windows: the `Bash` tool runs Git for Windows (MSYS) bash. `$HOME`,
+  forward slashes, `test -f`, `command -v`, heredocs, and `[[ … ]]` all
+  work. There is no reason to translate to `Test-Path`, `$env:USERPROFILE`,
+  `Get-Content`, `Where-Object`, `Get-ChildItem`, or backslash paths —
+  doing so will fail with `/usr/bin/bash: syntax error`.
+
+If a step genuinely needs OS branching, branch *inside* bash:
+
+```bash
+case "$(uname -s)" in
+  Darwin)               : ;;
+  Linux)                : ;;
+  MINGW*|MSYS*|CYGWIN*) : ;;
+esac
+```
+<!-- END shell-contract -->
+
+# /launchpad-destroy
+
+Destructive, owner-only verb. Tears down a Launchpad app end-to-end:
+the Cloudflare Pages project, Access app, custom hostname,
+launchpad-platform TF entries, and the app repo (archive-renamed,
+not deleted). Zero local platform-repo / terraform / Cloudflare /
+GitHub credentials needed — the bot owns all of it. CLI is a thin
+client.
+
+**Read this before running.** A clean destroy is irreversible after
+the ~30-day archive-recovery window (see "Recovery"). Smoke tests and
+orphan cleanup are the intended use case; if you are touching a live
+production app, get a second pair of eyes first.
+
+## Pre-flight
+
+You need a current Cf Access session and OWNER role on the app.
+Editors cannot destroy.
+
+```bash
+launchpad whoami
+# If this fails: launchpad login
+launchpad apps | grep <slug>
+# Confirm you are the owner (not an editor).
+```
+
+If `launchpad apps` doesn't show the slug, it doesn't exist — destroy
+exits 1 with `no app with slug <slug>`.
+
+## When NOT to use this skill
+
+- **Modifying an app's manifest.** Use `launchpad deploy` after
+  editing `launchpad.yaml`. Destroy doesn't reset config — it
+  removes the app entirely.
+- **Re-creating an app under the same name.** Run `launchpad destroy
+  <slug>`, wait for the lifecycle to reach `destroyed`, then
+  `launchpad create`. The slug is freed by the archive-rename step
+  in AC8.
+- **Cleaning up the app's GitHub history.** The destroy verb
+  archive-renames the repo (preserving history); it does not
+  hard-delete. Use `gh repo delete` if you genuinely need the repo
+  gone forever (irreversible after 90 days of GitHub's retention).
+
+## Two-step destructive confirmation
+
+```bash
+# Interactive (TTY): prompts for slug re-type + Y/N
+launchpad destroy <slug>
+
+# CI / non-TTY: BOTH flags are MANDATORY
+launchpad destroy <slug> --confirm-slug <slug> --yes
+
+# In a launchpad-app-<slug>/ clone — slug inferred from cwd
+cd launchpad-app-<slug>
+launchpad destroy --confirm-slug <slug> --yes
+```
+
+**Non-TTY behaviour:** missing either `--confirm-slug` or `--yes` in a
+non-TTY context exits 64 (`EX_USAGE`) with `"--confirm-slug and --yes
+required in non-interactive mode"`. CI invocations always set both.
+
+**TTY behaviour:** the verb prints a banner naming what's about to be
+destroyed, then prompts twice: (a) `Type the slug to confirm:` —
+operator must re-type the slug exactly (case-sensitive), and (b)
+`Are you sure? [y/N]`. Anything other than `y`/`yes` aborts (exit 1).
+Either flag can short-circuit its respective prompt.
+
+## What the verb does (server-side flow)
+
+1. **Server-side slug re-validation** (`checkSlug()` + `SLUG_REGEX`).
+2. **Owner-only authz** — `owner | break_glass` only; editor → 403.
+3. **Lifecycle precondition check** — see "Lifecycle states" below.
+4. **main.tf carve-out check** — pre-M-1182 apps that live in
+   `main.tf` cannot be destroyed by this verb (see "Carve-outs").
+5. **Per-app TF file pair existence probe** on launchpad-platform main.
+6. **Lifecycle → `destroying`**.
+7. **Enumerate open PRs on `launchpad-app-<slug>`.** Bot-authored PRs
+   are closed with a comment; human-authored PRs get a heads-up
+   comment (NOT closed — that's the human author's decision).
+8. **Atomic destroy PR** opens on `launchpad-platform`, deleting
+   `terraform/envs/prod/<slug>.tf` + `<slug>.allow.tf` in one commit.
+9. **`destroy:confirmed` label gate** must be applied by a non-author
+   for auto-merge.
+10. **Existing `tf-apply` workflow** destroys the Cf resources on
+    merge. There is NO new `tf-destroy` workflow — the standard
+    apply with the removed module is the teardown.
+11. **Archive-rename happens AFTER tf-apply terminal-success** — never
+    before (AC8). If tf-apply fails, the repo is untouched and
+    lifecycle moves to `destroy_failed` (recoverable).
+
+## Lifecycle states
+
+| State | Meaning | What you can do |
+|---|---|---|
+| `live` (or absent) | App is operational. | Destroy works. |
+| `provisioning` | Initial create still running. | Wait, then destroy. |
+| `failed` | Provisioning failed. | Destroy works (cleans up partial state). |
+| `destroying` | Destroy PR is open, tf-apply pending. | Re-running `launchpad destroy` is idempotent (returns the existing PR). |
+| `destroyed` | tf-apply succeeded + repo archive-renamed. | Re-running exits 0 with `already destroyed at <ts>`. Slug is free for re-use. |
+| `destroy_failed` | tf-apply on destroy PR failed or hung. | Re-running re-checks state; if not retriable, surfaces `platform-team intervention required`. App repo is **not** archive-renamed (recovery path stays clean). |
+
+## Carve-outs
+
+Legacy apps whose Terraform lives inside `terraform/envs/prod/main.tf`
+(rather than as a per-app `<slug>.tf` + `<slug>.allow.tf` pair) cannot
+be destroyed by this verb. The carve-out list is canonical in
+`portal-bot/src/reserved.ts` and currently covers `marquee`, `portal`,
+`canary`, `ai-cost-002`, `ai-cost-container`.
+
+Attempting destroy on a carve-out exits 1 with:
+
+```text
+launchpad destroy: <slug> is pre-M-1182 main.tf-resident; destroy is not supported. Contact platform-team.
+```
+
+If you genuinely need to tear down a main.tf-resident app, ping
+platform-team for a manual TF + repo cleanup.
+
+## Open PR handling
+
+When the destroy starts, the bot enumerates every open PR on
+`launchpad-app-<slug>` and splits them:
+
+- **Bot-authored PRs** (e.g. auto-deploy PRs the bot opened earlier):
+  closed with comment `"closed by launchpad destroy; the app is being
+  torn down"`.
+- **Human-authored PRs**: NOT closed. The bot comments on each with a
+  heads-up:
+
+    > NOTE: this app is being destroyed via launchpad destroy. This
+    > PR will become unmergeable when the platform-repo TF removal
+    > lands.
+    >
+    > Destroy PR: <url>
+
+  The human author decides what to do (close, salvage, etc.).
+
+In TTY mode the verb prints the human-PR list at confirmation time so
+you can pause if you didn't realise there were in-flight PRs.
+
+## Recovery — the archive-rename window
+
+After a clean destroy (`lifecycle: destroyed`), the app repo lives at
+`launchpad-app-<slug>-archived-<YYYYMMDD>` in the M-KOPA org, with
+GitHub's `archived: true` flag set. **There is no `launchpad
+undestroy` verb.** Recovery is operator self-service via `gh`:
+
+```bash
+# Rename back + unarchive (within ~30 days; check org policy).
+# `gh repo rename` takes a single positional <new-name>; the OLD
+# repo is specified via --repo (or -R).
+gh repo rename launchpad-app-<slug> \
+  --repo M-KOPA/launchpad-app-<slug>-archived-<YYYYMMDD>
+gh repo unarchive M-KOPA/launchpad-app-<slug>
+```
+
+This restores the **repo**, not the Cloudflare infrastructure — you
+would still need a fresh `launchpad create <slug>` (or a hand-rolled
+platform-repo PR re-adding the per-app TF pair) to bring the app
+back online.
+
+**The 30-day window is informational, not enforced by Launchpad** —
+the actual horizon is whatever GitHub's org policy is. If you
+suspect a destroy was a mistake, recover within hours, not weeks.
+
+## Exit codes
+
+- **0** — destroy initiated successfully, OR idempotent re-run on a
+  `destroyed` slug (no-op).
+- **1** — runtime error (auth, network, 403/404/409 from the bot).
+- **64** — usage error (invalid args, missing required flags in
+  non-TTY mode, slug mismatch on `--confirm-slug`).
+
+## Common error patterns + fixes
+
+### `launchpad destroy: session expired, run \`launchpad login\``
+
+Standard auth refresh. `launchpad login` once; the destroy command
+works again for the duration of the Cf Access session (~24h).
+
+### `not authorised to destroy app X (you must be an owner — editor role is not sufficient)`
+
+You're an editor, not the owner. Either:
+
+- Ask the current owner to transfer ownership via the portal admin UI:
+  `https://launchpad.m-kopa.us/admin/apps/<slug>` (then transfer back
+  after destroy, if you want).
+- Get break-glass access from platform-team for this specific
+  destroy (audited; one-shot).
+
+### `<slug> is pre-M-1182 main.tf-resident`
+
+See "Carve-outs". Platform-team manual cleanup is required.
+
+### `no per-app TF for <slug> in launchpad-platform/main`
+
+The app exists in the registry but has no per-app TF pair on
+platform main. This usually means: (a) the app was never fully
+provisioned (look at `lifecycle` — likely `failed`), or (b) the
+file pair was hand-removed outside of this verb. Either way:
+platform-team intervention.
+
+### `slug ${urlSlug} is already being destroyed`
+
+(No — this exits 200 idempotently now, not 409. If you see this
+message it's from an old bot. Update the bot.)
+
+### `slug <slug> is in destroy_failed state; platform-team intervention required`
+
+tf-apply on the destroy PR failed (commonly: a stuck Cf
+custom-hostname deletion). The app repo is NOT archive-renamed in
+this state — the recovery path is unblocked. Options:
+
+1. Re-run `launchpad destroy <slug>` to retry once the underlying
+   issue is fixed (e.g. tf-apply hang resolved).
+2. Contact platform-team for manual TF state surgery if re-running
+   doesn't move past the failure.
+
+## --json output
+
+For downstream scripts (CI cleanup jobs, automation):
+
+```bash
+launchpad destroy <slug> --confirm-slug <slug> --yes --json
+```
+
+```json
+{
+  "slug": "<slug>",
+  "lifecycle": "destroying",
+  "destroyPr": {
+    "number": 4242,
+    "url": "https://github.com/M-KOPA/launchpad-platform/pull/4242",
+    "branch": "bot/destroy/<slug>/<YYYYMMDD>",
+    "idempotent": false
+  },
+  "openBotPrs": [],
+  "openHumanPrs": [
+    { "number": 22, "title": "...", "htmlUrl": "...", "authorLogin": "alice" }
+  ]
+}
+```
+
+On an idempotent re-run against a `destroyed` slug:
+
+```json
+{
+  "slug": "<slug>",
+  "lifecycle": "destroyed",
+  "alreadyDestroyed": true,
+  "lifecycleAt": "2026-05-26T08:00:00Z"
+}
+```
+
+## Related skills
+
+- **`/launchpad-status`** — read the deployed manifest, compare to
+  local. Pair this with `launchpad pull <slug> --out backup.yaml`
+  before destroy if you want to keep the manifest for reference.
+- **`/launchpad-deploy`** — provision a new app (e.g. after a destroy
+  that frees the slug). Note the slug-lock during the destroy window:
+  `launchpad create <slug>` rejects if the slug is `destroying` or
+  `destroy_failed`.
+- **`/launchpad-deploy-status`** — diagnose `provisioning` /
+  `failed` lifecycle stages. Less relevant after destroy lands.
+
+## Anti-patterns
+
+- **Don't** run `gh repo delete` to clean up the app repo before
+  running `launchpad destroy` — the destroy needs to enumerate open
+  PRs on the repo and the platform PR opens fine without it, but
+  you'll lose the audit trail in the app repo's history.
+- **Don't** hand-edit `terraform/envs/prod/<slug>.tf` to "blank out"
+  the app — the bot still considers it live and `launchpad destroy`
+  is the only path that handles every dependent (Access app,
+  hostname, registry record, app repo). Manual TF edits leave
+  orphan Cloudflare state.
+- **Don't** parse the prose output of `launchpad destroy` in CI
+  scripts. Use `--json`.
+- **Don't** rely on a destroy PR auto-merging without the
+  `destroy:confirmed` label — a non-author must apply it. The label
+  is the audit gate; treating it as ceremony defeats AC6's two-pair-of-
+  eyes property.
+
+## Version
+
+This skill ships in launchpad-cli v0.14.0+ (M-1187 release).

package/skills/launchpad-onboard/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: launchpad-onboard
+description: One-time setup for the Launchpad CLI + Claude Code skill bundle. Verifies the `launchpad` CLI is installed and current, runs `launchpad whoami` to confirm the Cf Access session is fresh, and checks the bundled skills are installed and in lock-step with the CLI. Idempotent — safe to re-run any time. Use when someone says "set me up for Launchpad", "I just got a new machine and want to use Launchpad", "/launchpad-onboard", or any of the other launchpad-* skills fails on a prereq check.
+version: 0.23.0
+---
+
+<!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
+## Shell contract — read this first
+
+Every fenced `bash` block below MUST be sent to the `Bash` tool **verbatim**.
+Do not rewrite into PowerShell, cmd, zsh-isms, or "equivalent" forms.
+
+- macOS / Linux: the `Bash` tool runs system bash.
+- Windows: the `Bash` tool runs Git for Windows (MSYS) bash. `$HOME`,
+  forward slashes, `test -f`, `command -v`, heredocs, and `[[ … ]]` all
+  work. There is no reason to translate to `Test-Path`, `$env:USERPROFILE`,
+  `Get-Content`, `Where-Object`, `Get-ChildItem`, or backslash paths —
+  doing so will fail with `/usr/bin/bash: syntax error`.
+
+If a step genuinely needs OS branching, branch *inside* bash:
+
+```bash
+case "$(uname -s)" in
+  Darwin)               : ;;
+  Linux)                : ;;
+  MINGW*|MSYS*|CYGWIN*) : ;;
+esac
+```
+<!-- END shell-contract -->
+
+# /launchpad-onboard
+
+Run a prereq + auth health check for the Launchpad CLI and the Claude
+Code skill bundle. Surface a single pass/fail summary at the end with
+a copy-pasteable fix for any red row.
+
+## What this skill is responsible for
+
+This is the **only** skill that mutates the user's machine (it can
+trigger `launchpad login` and suggest installs). The other skills
+(`/launchpad-deploy`, `/launchpad-deploy-status`,
+`/launchpad-content-pr`, `/launchpad-status`, `/launchpad-destroy`)
+assume the machine is already onboarded and fail loudly if a prereq is
+missing — pointing back here.
+
+## Zero non-Launchpad dependencies
+
+Under Model A (M-1216), the CLI is fully self-contained: it talks
+straight to the bot via Cf Access OAuth and never shells out to `gh`,
+`jq`, `curl`, `git`, or any other system tool. **External users with
+no M-KOPA GitHub access are first-class.** This skill therefore
+checks only two things: the `launchpad` binary is on PATH at the
+expected version, and the bundled skills are installed and synced.
+
+There is no `gh auth` check, no `jq` probe, no `curl` smoke-test.
+A regression that re-introduces such a dependency surfaces in the
+`launchpad-cli-e2e` zero-deps CI matrix, not here.
+
+## Run sequence
+
+Execute the checks below in order. Collect a `{ ok | fix }` row per
+check and print them all at the end as a table. Do NOT stop early on
+the first red row — finish the full sweep so the user sees every
+issue in one pass.
+
+### 1. `launchpad` CLI installed
+
+```bash
+launchpad --version
+```
+
+- **Missing** (`command not found`) — install it:
+  - **Public npm (primary, all platforms):**
+    `npm i -g @m-kopa/launchpad-cli` — no `~/.npmrc` setup, no auth
+    token, no antivirus block. Works on macOS, Linux, and Windows.
+  - **Platform channel (legacy / air-gapped):** download and run the
+    installer from https://get.launchpad.m-kopa.us. On Windows the
+    self-contained `.ps1` may trip Defender — prefer the npm install
+    above.
+- **Below the version bundled with this skill** (see step 4 below):
+  `npm update -g @m-kopa/launchpad-cli` (or re-run the platform
+  installer). Then `launchpad skills update` to re-sync the skill bundle.
+
+### 2. Session is present and fresh
+
+`launchpad whoami` is the canonical health check. It reads the
+on-disk session, decodes the JWT (without validating its signature —
+that's the bot's job), and prints identity + expiry + role per app.
+A session that's expired or missing surfaces as a clear "session
+expired, run `launchpad login`" error from the verb itself; no manual
+file inspection required.
+
+```bash
+launchpad whoami
+```
+
+- **Exit 0** → session is valid; identity and expiry are printed.
+- **"No session — run `launchpad login`"** → no session file on
+  disk. Run `launchpad login` (opens a browser; sign in via
+  Cloudflare Access SSO).
+- **"session expired, run `launchpad login`"** → refresh tokens
+  rotate; re-authenticate.
+- **Any other error** → surface the message verbatim. Do not fall
+  back to inspecting `~/.launchpad/session.json` by hand — the file
+  is internal to the CLI and its shape is not a stable contract.
+
+### 3. Skill bundle installed at `$HOME/.claude/skills/launchpad-*/`
+
+```bash
+launchpad skills list
+```
+
+Expected: the launchpad-* skills are all present with a `version:`
+matching the CLI.
+
+- **Any skill missing** (or `$HOME/.claude/skills/` doesn't exist):
+  ```bash
+  launchpad skills install
+  ```
+
+### 4. Skill bundle version matches the installed CLI
+
+`launchpad skills list` annotates each skill with its `version:`
+frontmatter. The CLI release pipeline stamps both the CLI and the
+bundled skills from `package.json` (see
+`scripts/sync-skill-contract.sh`); CI rejects any PR that lets them
+drift. So a mismatch here means the user has an old skill bundle on
+disk, not a release-engineering bug.
+
+If `launchpad skills list` reports any skill at a different version
+than `launchpad --version`:
+
+```bash
+launchpad skills update
+```
+
+This re-copies the bundled skills out of the installed CLI package
+and re-syncs the version on disk.
+
+## Summary table
+
+At the end, print a single table like:
+
+```
+Check                                  Status   Fix
+─────────────────────────────────────────────────────────────────────
+launchpad CLI installed                ✓        —
+launchpad whoami succeeds (session)    ✗        launchpad login
+Skill bundle installed                 ✓        —
+Skill bundle ↔ CLI version match       ✓        —
+```
+
+If every row is `✓`, finish with a single line:
+
+```
+✓ All checks passed — you can run /launchpad-deploy.
+```
+
+Otherwise finish with:
+
+```
+✗ N check(s) failed — apply the fixes above and re-run /launchpad-onboard.
+```
+
+## Don'ts
+
+- Do **not** run `launchpad login` without telling the user first — it
+  opens a browser. State that it's about to happen and what they need
+  to do (sign in via Cloudflare Access SSO).
+- Do **not** run destructive ops (e.g. `npm uninstall`, `rm`) on the
+  user's machine even if a check fails — only suggest the fix; the
+  user runs it themselves.
+- Do **not** probe for `gh`, `jq`, `curl`, or `git` and treat their
+  absence as a failure. The CLI does not depend on any of them under
+  Model A — flagging them red is a misleading prereq from the
+  pre-M-1216 era.
+- Do **not** read `~/.launchpad/session.json` directly. Use
+  `launchpad whoami`; the file is an internal artefact.
+- Do **not** retry indefinitely. One pass, one summary, done.