@m-kopa/launchpad-cli 0.26.1 → 0.27.1

package/skills/launchpad-destroy/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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.26.1
+description: Tear down a Launchpad app end-to-end via `launchpad destroy` — Cloudflare Pages project, edge-auth wiring (gateway KV/audience entries, or the Access app for `auth: access` apps), custom hostname, platform-repo TF, 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.27.1
 ---
 
 <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -31,9 +31,11 @@ esac
 # /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 /
+the Cloudflare Pages project, the app's edge-auth wiring (gateway
+KV/audience entries for gateway-fronted apps — the default; the
+Access app for `auth: access` apps), custom hostname,
+launchpad-platform TF, 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.
 
@@ -44,8 +46,8 @@ 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.
+You need a current session (`launchpad login`) and OWNER role on the
+app. Editors cannot destroy.
 
 ```bash
 launchpad whoami
@@ -64,8 +66,8 @@ exits 1 with `no app with slug <slug>`.
   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.
+  `launchpad init` + `launchpad deploy` from the app's working
+  directory. 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
@@ -97,26 +99,78 @@ Either flag can short-circuit its respective prompt.
 
 ## What the verb does (server-side flow)
 
+Every destroy starts with the same shared steps:
+
 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
+4. **Three-way TF-shape fork.** The bot probes where the app's
+   Terraform lives on launchpad-platform main:
+   - `main.tf`-resident (pre-M-1182) → **rejected** (see
+     "Carve-outs").
+   - **Per-app workspace** (`terraform/envs/prod/apps/<slug>/` with
+     isolated state — the default shape for current apps) → the
+     workspace path below.
+   - **Legacy file pair** (`<slug>.tf` + `<slug>.allow.tf` in the
+     shared root) → the legacy PR path below.
+5. **Lifecycle → `destroying`**, then **enumerate open PRs on
+   `launchpad-app-<slug>`** (both paths): 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).
+
+### Per-app-workspace path (the current default)
+
+There is **no destroy PR and no `destroy:confirmed` label** on this
+path. Workspace apps live in isolated TF state, so there is no
+shared apply to pick up a file deletion — teardown is an explicit
+`terraform destroy`:
+
+1. The bot fires an **HMAC-signed `repository_dispatch`**
+   (`tf-destroy-per-app`): it signs `<slug>|<exp>` with a secret
+   only the bot holds (short-lived token, ~10 min). A
+   `repository_dispatch` already requires a repo-scoped token, so
+   the run cannot be fired from the Actions UI; the workflow
+   re-verifies the signature fail-closed AND re-checks
+   `lifecycle == destroying` before anything destructive runs.
+2. The workflow runs **`terraform destroy` against the app's
+   isolated R2 state** (while the workspace files are still
+   present), then deletes the state object so the slug is
+   reclaimable.
+3. On run success the bot opens **and auto-merges** a pure
+   config-cleanup PR deleting `terraform/envs/prod/apps/<slug>/`
+   (branch `bot/destroy-workspace/<slug>/<YYYYMMDD>`) — the
+   resources and state are already gone by then; merging just stops
+   a later per-app apply from re-creating the app.
+4. **Archive-rename + `lifecycle: destroyed` happen only after the
+   destroy run concludes successfully.** A failed run →
+   `destroy_failed`, repo untouched; re-running `launchpad destroy`
+   re-dispatches the teardown.
+
+### Legacy file-pair path (shared-root apps only)
+
+Still shipped, for apps whose TF is the shared-root `<slug>.tf` +
+`<slug>.allow.tf` pair:
+
+1. **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
+2. **`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).
+3. **Existing `tf-apply` workflow** destroys the Cf resources on
+   merge. There is NO `tf-destroy` workflow on this path — the
+   standard apply with the removed module is the teardown.
+4. **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`.
+
+## What destroy does NOT remove
+
+**The app's D1 database is never dropped.** D1 databases are
+bot-API-created (not in the app's TF), and no destroy path touches
+them. The bot's D1 handling is create-or-adopt **by name**: the data
+survives the destroy, and a later `launchpad init` + `launchpad
+deploy` of the **same slug** re-adopts the existing database — your
+data is still there. If you genuinely need the data gone, that is a
+platform-team request, not a destroy side-effect.
 
 ## Lifecycle states
 
@@ -124,10 +178,10 @@ Either flag can short-circuit its respective prompt.
 |---|---|---|
 | `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). |
+| `failed` | Provisioning failed. | Destroy works (cleans up partial state). If the app is actually live and serving, consider `launchpad recover <slug>` first — it repairs the record instead of tearing down. |
+| `destroying` | Teardown in flight (workspace: destroy run dispatched; legacy: destroy PR open, tf-apply pending). | Re-running `launchpad destroy` is idempotent — workspace: re-dispatches the run; legacy: returns the existing PR. |
+| `destroyed` | Teardown succeeded + repo archive-renamed. | Re-running exits 0 with `already destroyed at <ts>`. Slug is free for re-use. |
+| `destroy_failed` | The teardown failed or hung. | **Workspace path:** re-run `launchpad destroy` — it re-dispatches from the failure point. **Legacy path:** re-run is rejected with `platform-team intervention required` (409). On both, the app repo is **not** archive-renamed (recovery path stays clean). |
 
 ## Carve-outs
 
@@ -163,10 +217,14 @@ When the destroy starts, the bot enumerates every open PR on
     >
     > Destroy PR: <url>
 
-  The human author decides what to do (close, salvage, etc.).
+  The human author decides what to do (close, salvage, etc.). (The
+  `Destroy PR: <url>` line appears on the legacy path only — the
+  workspace path has no destroy PR at initiation time.)
 
-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.
+The PR split is computed server-side once the destroy is initiated;
+the CLI prints the bot/human PR lists in its post-initiation render
+(after confirmation, not before), so review them there if you didn't
+realise there were in-flight PRs.
 
 ## Recovery — the archive-rename window
 
@@ -185,9 +243,11 @@ 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.
+would still need a fresh `launchpad init` + `launchpad deploy` (or a
+hand-rolled platform-repo PR re-adding the per-app TF) to bring the
+app back online. Remember the app's D1 database survived the destroy
+(see "What destroy does NOT remove") — a same-slug re-provision
+re-adopts it.
 
 **The 30-day window is informational, not enforced by Launchpad** —
 the actual horizon is whatever GitHub's org policy is. If you
@@ -205,16 +265,17 @@ suspect a destroy was a mistake, recover within hours, not weeks.
 
 ### `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).
+Standard auth refresh. `launchpad login` once; the session then stays
+fresh by silent refresh as you use the CLI.
 
-### `not authorised to destroy app X (you must be an owner — editor role is not sufficient)`
+### `not authorised to destroy app X (you must be an owner)`
 
-You're an editor, not the owner. Either:
+You're an editor, not the owner — editor role is not sufficient for
+destroy. 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).
+  `https://portal.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).
 
@@ -224,11 +285,12 @@ 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.
+The app exists in the registry but has no per-app TF on platform
+main — neither an `apps/<slug>/` workspace nor a `<slug>.tf` +
+`<slug>.allow.tf` file pair (the bot probes both before this 409).
+This usually means: (a) the app was never fully provisioned (look
+at `lifecycle` — likely `failed`), or (b) the TF was hand-removed
+outside of this verb. Either way: platform-team intervention.
 
 ### `slug ${urlSlug} is already being destroyed`
 
@@ -237,14 +299,17 @@ 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:
+This 409 fires on the **legacy file-pair path only**: tf-apply on
+the destroy PR failed (commonly: a stuck Cf custom-hostname
+deletion), and the file-pair model has no self-service retry —
+contact platform-team for manual TF state surgery.
+
+On the **per-app-workspace path** a `destroy_failed` slug never
+returns this error: re-running `launchpad destroy <slug>` simply
+re-dispatches the teardown run from the failure point.
 
-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.
+On both paths the app repo is NOT archive-renamed in this state —
+the recovery path is unblocked.
 
 ## --json output
 
@@ -254,6 +319,29 @@ For downstream scripts (CI cleanup jobs, automation):
 launchpad destroy <slug> --confirm-slug <slug> --yes --json
 ```
 
+The shape is per-path. **Per-app-workspace apps** (the default) have
+no destroy PR at initiation — the response carries a `path`
+discriminant instead:
+
+```json
+{
+  "slug": "<slug>",
+  "lifecycle": "destroying",
+  "path": "per-app-workspace",
+  "openBotPrs": [],
+  "openHumanPrs": [
+    { "number": 22, "title": "...", "htmlUrl": "...", "authorLogin": "alice" }
+  ]
+}
+```
+
+(The workspace config-cleanup PR — branch
+`bot/destroy-workspace/<slug>/<YYYYMMDD>` — is opened and auto-merged
+by the bot later, after the destroy run succeeds; it never appears in
+this response.)
+
+**Legacy file-pair apps** return the destroy PR:
+
 ```json
 {
   "slug": "<slug>",
@@ -287,12 +375,18 @@ On an idempotent re-run against a `destroyed` slug:
 - **`/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`** — provision a new app via `launchpad init`
+  + `launchpad deploy` (e.g. after a destroy that frees the slug).
+  Note the slug-lock during the destroy window: creating an app is
+  rejected while the slug is `destroying` or `destroy_failed`.
 - **`/launchpad-deploy-status`** — diagnose `provisioning` /
   `failed` lifecycle stages. Less relevant after destroy lands.
+  If the app shows `failed` but is actually live and serving, reach
+  for `launchpad recover <slug>` (documented there) before assuming
+  destroy + re-create is the fix — recover repairs the registry
+  record against live state. (Recover refuses destroy-side states —
+  `destroying` / `destroyed` / `destroy_failed` are owned by this
+  verb.)
 
 ## Anti-patterns
 
@@ -300,17 +394,21 @@ On an idempotent re-run against a `destroyed` slug:
   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** hand-edit the app's per-app TF (the
+  `terraform/envs/prod/apps/<slug>/` workspace, or legacy
+  `<slug>.tf`) to "blank out" the app — the bot still considers it
+  live and `launchpad destroy` is the only path that handles every
+  dependent (edge-auth wiring, 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.
+- **Don't** rely on a **legacy-path** 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. (The label gate does not exist on the
+  per-app-workspace path — there is no destroy PR there; the
+  equivalent control is the bot-only HMAC-signed dispatch + the
+  workflow's lifecycle re-check.)
 
 ## Version
 

package/skills/launchpad-onboard/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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.26.1
+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 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.27.1
 ---
 
 <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -45,9 +45,10 @@ 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
+Under Model A (M-1216), the CLI is fully self-contained: it signs in
+through the platform auth gateway and talks straight to the bot with
+that bearer credential, never shelling 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.
@@ -78,8 +79,14 @@ launchpad --version
     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.
+  run `launchpad update` — the CLI's built-in self-update. It detects
+  the install channel itself (public npm vs the platform channel) and
+  upgrades in place; `launchpad update --check` reports current vs
+  latest without installing anything (exit 10 = update available).
+  If `update` can't tell which package manager owns the global
+  install, it prints the explicit upgrade commands — run the right
+  one (e.g. `npm update -g @m-kopa/launchpad-cli`). Then
+  `launchpad skills update` to re-sync the skill bundle.
 
 ### 2. Session is present and fresh
 
@@ -96,22 +103,44 @@ 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.
+  disk. Run `launchpad login` (opens a browser; sign in with your
+  M-KOPA Microsoft account via the Launchpad auth gateway).
+- **"session expired, run `launchpad login`"** → re-authenticate.
+  Sessions normally stay fresh on their own — the CLI silently
+  rotates a refresh token as you use it — so this only appears after
+  roughly a week of not using the CLI (or a hard cap of 30 days),
+  not on a daily cadence. The short access-token expiry `whoami`
+  prints is by design; verbs refresh it automatically.
 - **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.
 
+**Upgrading from CLI ≤ 0.26.x:** the login flow moved from Cloudflare
+Access to the platform auth gateway on 2026-06-12, and old clients are
+hard-broken against the bot by design. The fix is always the same two
+commands:
+
+```bash
+launchpad update
+launchpad login
+```
+
+(If the gateway flow itself fails, the CLI auto-falls back to the
+legacy flow with a deprecation notice; `LAUNCHPAD_AUTH_LEGACY=1`
+forces it outright. It is a temporary escape hatch slated for
+removal — don't reach for it unless platform support says so.)
+
 ### 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.
+Expected: the launchpad-* skills **plus the bundled `marquee-share`
+skill** are all present. The launchpad-* skills each carry a
+`version:` matching the CLI; `marquee-share` is vendored from
+`M-KOPA/marquee` and prints `(no version)` — that is normal, not a
+drift signal.
 
 - **Any skill missing** (or `$HOME/.claude/skills/` doesn't exist):
   ```bash
@@ -166,7 +195,7 @@ Otherwise finish with:
 
 - 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).
+  to do (sign in with their M-KOPA Microsoft account).
 - 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.