@m-kopa/launchpad-cli 0.77.0 → 0.78.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: launchpad-deploy
3
3
  description: Walk a Launchpad user through deploying an app from their local working directory (Model A — `launchpad init` + `launchpad deploy`). Wraps the CLI verbs end-to-end: detects the app shape, scaffolds `launchpad.yaml`, resolves the allowed Entra group via `launchpad groups`, bundles the CWD via `launchpad deploy`, and watches the rollout via `launchpad status`. Use when someone says "deploy a new app", "ship my app to Launchpad", "/launchpad-deploy", "I have an app locally — get it on Launchpad", or any variant. Resume/abandon for legacy in-flight provisioning is at the bottom.
4
- version: 0.77.0
4
+ version: 0.78.0
5
5
  ---
6
6
 
7
7
  <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -247,14 +247,16 @@ silently overwrite it.
247
247
 
248
248
  **What `init` does not create.** `launchpad init` writes `./launchpad.yaml`
249
249
  and adds `.env` / `.env.local` to `.gitignore`. For a `static` app it also
250
- writes a starter `static/index.html` when none exists. It writes no app
251
- code: for `react` and `react+api` the project (`package.json`, lockfile,
252
- `src/`, `functions/`) is the user's own, and `launchpad deploy` ships what is
253
- already in the folder. If the folder is empty, tell the user to add their
254
- app first; do not expect `init` to scaffold one. For a `react+api` app follow
255
- §A.2b, which starts from the platform's starter files. (`--secure-template`, which
256
- scaffolds a `react+api` API, needs CLI 0.77.0 or newer: check
257
- `launchpad --version` before offering it.)
250
+ writes a starter `static/index.html` when none exists. For `react` it writes
251
+ no app code: the project (`package.json`, lockfile, `src/`) is the user's own,
252
+ and `launchpad deploy` ships what is already in the folder. If the folder is
253
+ empty, tell the user to add their app first. For `react+api`, CLI 0.78.0 and
254
+ newer also writes a working starter app (§A.2b) unless `--no-starter` is
255
+ passed; it writes nothing when the folder already has a `package.json`, a
256
+ lockfile or a `vite.config.*`, and never overwrites a file. Check
257
+ `launchpad --version` before relying on it. (`--secure-template`, which
258
+ scaffolds a secure `react+api` router, needs CLI 0.77.0 or newer; with the
259
+ starter, the secure router replaces the starter router.)
258
260
 
259
261
  **Stack constraints by app-type** (single source of truth:
260
262
  `launchpad-platform/ARCHITECTURE.md § Tech Stack` and `PATTERNS.md §
@@ -280,46 +282,36 @@ the existing app uses any of these, plan the swap **before** picking
280
282
  a slug — do not deploy first and port later. What the bot *does*
281
283
  enforce at deploy time is the gate set in §A.5.
282
284
 
283
- ### A.2b React API app: the proven recipe
285
+ ### A.2b React API app: the short path
284
286
 
285
287
  A `react+api` app on dispatch went live from one `launchpad deploy` in 477 s
286
- (observed on 16-17 Nov 2026) when it followed these steps. Two earlier runs
287
- that used their own `package.json` and their own `functions/api/*.js`, or a
288
- newer bun, failed the first delivery build. Follow the steps in order.
288
+ (observed on 16-17 Nov 2026) when it started from the platform's files. Two
289
+ earlier runs that used their own `package.json` and their own
290
+ `functions/api/*.js`, or a newer bun, failed the first delivery build. CLI
291
+ 0.78.0 and newer writes those files for you, so the path is short.
289
292
 
290
293
  **Why the app must start from the platform's files.** The bootstrap pull
291
- request seeds a `react+api` app with a starter `package.json`, `bun.lock`,
292
- `tsconfig.json` and `functions/api/[[path]].ts` (see
293
- `portal-bot/src/bootstrap-manifest.ts`). That `[[path]].ts` is a Hono router
294
+ request seeds a `react+api` app with a `functions/api/[[path]].ts` Hono router
294
295
  that imports `hono` and `@m-kopa/platform-auth`. The first delivery build
295
296
  compiles it, so if the owner's `package.json` lacks those two dependencies the
296
297
  build fails with `Could not resolve "hono/cloudflare-pages"` and the app ends
297
298
  `provisioning_failed` at `deployment_verified`.
298
299
 
299
- 1. **Get the starter files.** From `M-KOPA/launchpad-template`, copy the
300
- `react-api/starter/` folder (`package.json`, `bun.lock`, `tsconfig.json`)
301
- into the app folder, and `react-api/functions/api/[[path]].ts` to
302
- `functions/api/[[path]].ts`. Build the app on these files; do not start from
303
- a fresh `npm create`.
304
- 2. **Keep the two dependencies**, `hono` and `@m-kopa/platform-auth`, in
305
- `package.json`. Add the app's own packages (for example `react`,
306
- `react-dom`, `vite`) beside them.
307
- 3. **Add API routes inside that router**, in `functions/api/[[path]].ts`.
308
- Never add a second functions file such as `functions/api/hello.js` beside
309
- it: it is a competing route.
310
- 4. **Add a `build` script**, for example `"build": "vite build"`; the starter
311
- has none. The build output (`dist`) must contain no hidden files or
312
- folders: do not create `public/.gitkeep`, because Vite copies it into
313
- `dist` and dispatch refuses the delivery.
314
- 5. **Install with bun 1.3.4**, which also rewrites the lockfile at version 1
315
- (see "bun version" below):
316
-
317
- ```bash
318
- npx --yes bun@1.3.4 install
319
- ```
320
-
321
- 6. **Run the local gate** with the same bun, in the app folder. The last
322
- command is the functions compile that the delivery workflow runs:
300
+ 1. **Run `launchpad init --type react+api`** (with the other init flags from
301
+ §A.2) in an empty folder. It writes the manifest and a working starter:
302
+ `package.json` (with `hono`, `@m-kopa/platform-auth`, React, Vite and a
303
+ `build` script), a `bun.lock` written by bun 1.3.4, `tsconfig.json`, the
304
+ router `functions/api/[[path]].ts`, a page (`index.html`, `src/main.jsx`) and
305
+ `vite.config.js`; the manifest gets `spec.build`. `--no-starter` writes only
306
+ the manifest. Check `launchpad --version` shows 0.78.0 or newer first; an
307
+ older CLI writes no starter.
308
+ 2. **Add API routes inside the starter's router**, in
309
+ `functions/api/[[path]].ts`. Never add a second functions file such as
310
+ `functions/api/hello.js` beside it: it is a competing route. Add the app's
311
+ own packages with `npx --yes bun@1.3.4 add <package>` so the lockfile stays
312
+ at version 1.
313
+ 3. **Run the local gate** with bun 1.3.4, in the app folder. The last command is
314
+ the functions compile that the delivery workflow runs:
323
315
 
324
316
  ```bash
325
317
  npx --yes bun@1.3.4 install --frozen-lockfile --ignore-scripts
@@ -329,21 +321,28 @@ build fails with `Could not resolve "hono/cloudflare-pages"` and the app ends
329
321
  npx --yes wrangler@4.136.3 pages functions build functions --outdir "$(mktemp -d)" --compatibility-date 2026-07-27 --compatibility-flags nodejs_compat
330
322
  ```
331
323
 
332
- Every command must exit 0. The functions compile is the check that catches
333
- a missing `hono` or `@m-kopa/platform-auth`; `launchpad validate` and
334
- `launchpad deploy --dry-run` do not. Running `bun audit` on your own app
335
- is good practice too.
336
- 7. **Then run `launchpad init`**, after the install, so the manifest gets its
337
- `spec.build` block (`bun install --frozen-lockfile && bun run build`,
338
- destination `dist`). Run before the install, `init` wrote no `spec.build`
339
- (observed on 16 Nov 2026). Check the block is there. Add `test/**` and
340
- `eslint.config.js` to `spec.app.include` if the app has them.
341
- 8. **`launchpad validate`, then ONE `launchpad deploy`.** The first deploy
324
+ Every command must exit 0. The functions compile catches a missing `hono` or
325
+ `@m-kopa/platform-auth`; `launchpad validate` and `launchpad deploy
326
+ --dry-run` do not.
327
+ 4. **`launchpad validate`, then ONE `launchpad deploy`.** The first deploy
342
328
  ships the content; do not deploy again to check.
343
329
 
330
+ **When `init` writes no starter.** `init` writes nothing beyond the manifest
331
+ when the folder already has a `package.json`, a lockfile or a `vite.config.*`,
332
+ and it never overwrites a file; it says why. For such an existing app, bring it
333
+ in line by hand: keep `hono` and `@m-kopa/platform-auth` in `package.json`
334
+ (the platform's reference files are `react-api/starter/` and
335
+ `react-api/functions/api/[[path]].ts` in `M-KOPA/launchpad-template`), put the
336
+ routes in the one `functions/api/[[path]].ts` router, give `package.json` a
337
+ `build` script such as `"build": "vite build"`, make sure the manifest has
338
+ `spec.build` (`bun install --frozen-lockfile && bun run build`, destination
339
+ `dist`), install with `npx --yes bun@1.3.4 install`, then run steps 3 and 4.
340
+
344
341
  Two traps (observed on 16-17 Nov 2026):
345
342
 
346
- - **Hidden files in the build output** (step 4).
343
+ - **Hidden files in the build output.** The build output (`dist`) must contain
344
+ no hidden files or folders: do not create `public/.gitkeep`, because Vite
345
+ copies it into `dist` and dispatch refuses the delivery.
347
346
  - **A global `~/.npmrc` that routes `@m-kopa` to another registry** (for
348
347
  example GitHub Packages) can make the install 404 for
349
348
  `@m-kopa/platform-auth`, which is on the public npm registry. Put one line
@@ -354,16 +353,14 @@ Two traps (observed on 16-17 Nov 2026):
354
353
  (`bun-version: "1.3.4"`). A lockfile written by bun 1.4 or newer has
355
354
  `"lockfileVersion": 2`, which bun 1.3.4 cannot read: the first delivery build
356
355
  fails at "Install dependencies" with `Unknown lockfile version`, and the app
357
- ends `provisioning_failed` at `deployment_verified`. Check before deploying:
356
+ ends `provisioning_failed` at `deployment_verified`. `launchpad deploy` now
357
+ checks this itself before it uploads anything (see §A.5, "Pre-flight checks").
358
+ If it reports a lockfile problem, the fix is:
358
359
 
359
360
  ```bash
360
- bun --version
361
- grep lockfileVersion bun.lock
361
+ npx --yes bun@1.3.4 install
362
362
  ```
363
363
 
364
- The second line must show `"lockfileVersion": 1`. If it shows 2, regenerate
365
- with `npx --yes bun@1.3.4 install`.
366
-
367
364
  ### A.3 Deliberately share with an Entra group
368
365
 
369
366
  The CLI resolves Entra groups via the bot's `/groups` endpoint
@@ -515,6 +512,25 @@ for `react+api`); it leaves out lint config (`eslint.config.*`) and tests
515
512
  (`test/**`, `vitest.config.*`). Add them to `spec.app.include` when the app's
516
513
  CI needs them.
517
514
 
515
+ **Pre-flight checks (CLI 0.78.0 and newer).** Before it uploads anything,
516
+ `launchpad deploy` looks at the bundle for two shapes that fail the delivery
517
+ build. It refuses (exit 1, nothing uploaded) only when the build is certain to
518
+ fail, and prints a warning, then continues, in every other case:
519
+
520
+ - a `bun.lock` with `"lockfileVersion"` 2 or newer, which the build's bun 1.3.4
521
+ cannot read. It is refused only for a dispatch app whose build runs
522
+ `bun install --frozen-lockfile` on that lockfile; elsewhere it warns. Fix:
523
+ `npx --yes bun@1.3.4 install`.
524
+ - a dispatch `react+api` app that ships no API router of its own and whose
525
+ `package.json` is missing, is not valid JSON, or lacks `hono` or
526
+ `@m-kopa/platform-auth` (the seeded router imports both). A package missing
527
+ for a router the app does ship only warns. Fix: `npx --yes bun@1.3.4 add hono
528
+ @m-kopa/platform-auth`, or the install command above.
529
+
530
+ Each refusal names the flag `--allow-preflight-failure`, which turns refusals
531
+ into warnings. Do not pass it to get past a refusal: fix the named file first.
532
+ It is valid only for a content deploy.
533
+
518
534
  ### Container apps — use `auth: gateway` (AIO-811)
519
535
 
520
536
  Container apps (`type: container`) sign in through the same Entra auth gateway as Pages apps. `launchpad init` scaffolds new container apps with `auth: gateway` by default; keep it. Pass `--auth access` only for a legacy Access app.
@@ -584,10 +600,11 @@ fresh slug auto-provisions:
584
600
 
585
601
  - **Time.** Expect 5-10 minutes from the bot accepting the deploy to `live`
586
602
  (three runs on 16-17 Nov 2026 took about 8 to 9.5 minutes). The CLI waits
587
- about 480 s, and returns earlier if the deploy fails inside that window.
603
+ about 8 minutes, and returns earlier if the deploy fails inside that window.
588
604
  - **Exit 0 after `Still provisioning (stage: ...)` is not success.** The wait
589
- expired and the app is not live yet; the CLI still exits 0. Never tell the
590
- user it is deployed. Run:
605
+ expired and the app is not live yet; the CLI still exits 0, and its last line
606
+ now reads `Deploy NOT finished: <slug> is still provisioning and is not live
607
+ yet`. Never tell the user it is deployed. Run:
591
608
 
592
609
  ```bash
593
610
  launchpad watch <slug>
@@ -604,13 +621,17 @@ fresh slug auto-provisions:
604
621
  `503 enforced_access_unavailable` ("cannot verify enforced access from
605
622
  Terraform - retry shortly") is a retryable 503 too: same wait, same limit.
606
623
  Do not change the manifest, the groups or the slug to get past it.
607
- - **A failed bootstrap `npm-audit` is a platform fault, not your lockfile.**
624
+ - **A failed bootstrap check is a platform fault, not your lockfile.**
608
625
  The bot's bootstrap pull request runs CI (the `launchpad-review` workflow) on
609
626
  the platform's starter files, not on your app. If it fails (for example
610
627
  `bootstrap PR #1 CI failed: failed checks: npm-audit`), the first deploy ends
611
- `bot_pr_ci_failed`. Do not change your lockfile, do not retry, do not use
612
- another slug; run `/launchpad-report`. Running `bun audit` on your own app is
613
- still good practice, but it does not predict this check.
628
+ `bot_pr_ci_failed`. The starter's advisories and the audit script are fixed
629
+ for new apps, so this should not happen; if it does, report it with
630
+ `/launchpad-report`. Do not change your lockfile and do not retry under
631
+ another slug. `launchpad status` may still suggest running `bun audit
632
+ --prod`; that does not predict this check. To clear the slug, the owner runs
633
+ `launchpad destroy <slug> --confirm-slug <slug> --yes` (see
634
+ `/launchpad-deploy-status`).
614
635
 
615
636
  What the bootstrap CI runs on the first PR, on the starter files (jobs `lint`,
616
637
  `typecheck`, `test`, `gitleaks`, `npm-audit`):
@@ -677,6 +698,10 @@ Flags — there is nothing useful to pass on the Model A path:
677
698
  Run `/launchpad-status` to confirm; `/launchpad-content-pr` is no
678
699
  longer needed under Model A (the first deploy already shipped your
679
700
  content)."
701
+ - **`couldn't reach the served URL to verify: served URL redirected (HTTP 302)`**
702
+ after a successful deploy is expected for an app behind gateway sign-in: the
703
+ CLI has no browser session, so the app sends it to sign-in. It is not a
704
+ failure. Confirm with `launchpad status <slug>`.
680
705
  - **Terminal failure stages** — `validator_rejected`,
681
706
  `tf_apply_failed`, `bot_pr_ci_failed`, `abandoned`, `failed` → run
682
707
  `/launchpad-deploy-status <slug>` and surface the failure reason
@@ -687,15 +712,20 @@ Flags — there is nothing useful to pass on the Model A path:
687
712
  them verbatim and let the user fix and re-`launchpad deploy`.
688
713
  - **First deploy ended `provisioning_failed` / `bot_pr_ci_failed`** (for
689
714
  example `bootstrap PR #1 CI failed: failed checks: npm-audit`) → a platform
690
- fault; the user cannot retry or remove it themselves. Do not create a second slug and do not
715
+ fault. The owner can now free the slug: `launchpad destroy <slug>
716
+ --confirm-slug <slug> --yes` releases it in seconds (proven on production on
717
+ 17 Nov 2026). Do not create a second slug before that destroy, and do not
691
718
  loop `deploy`, `recover`, `--resume`, `--abandon` or `--allow-unguarded`:
692
719
  none of them clears it. Follow `/launchpad-deploy-status` § "First deploy
693
- stuck at `provisioning_failed`" and run `/launchpad-report` with the slug.
720
+ stuck at `provisioning_failed`", and run `/launchpad-report` with the slug
721
+ if the destroy is refused.
694
722
  - **First deploy ended `provisioning_failed` at `deployment_verified`** with
695
723
  `dispatch delivery refused: build-failed` (the bootstrap PR merged, the first
696
724
  delivery build failed) → follow `/launchpad-deploy-status` § "First deploy
697
725
  failed at `deployment_verified`". Do not use `launchpad recover`: it does not
698
- apply to dispatch apps even when `launchpad status` suggests it.
726
+ apply to dispatch apps. From CLI 0.78.0, `launchpad status` no longer
727
+ suggests it for a dispatch app; it says to fix the cause, destroy and deploy
728
+ again. An older CLI may still print the `recover` line: ignore it.
699
729
  - **Dispatch delivery refused** (`launchpad status` shows `v2 delivery:
700
730
  state refused`) → surface the `failed at` reason verbatim. For
701
731
  `hidden build output is not supported`, follow the fix in §A.2 and
@@ -707,8 +737,8 @@ Flags — there is nothing useful to pass on the Model A path:
707
737
  was moved from dispatch to Pages needs the platform team to return
708
738
  it to dispatch (`launchpad migrate` only moves live Pages apps), so
709
739
  offer `/launchpad-report` with the slug and the error.
710
- - **Terminal-failed but the app is actually serving** → `launchpad
711
- recover <slug>`. The bot re-derives reality from live Cloudflare
740
+ - **Terminal-failed but the app is actually serving** (a Pages app; `recover`
741
+ refuses dispatch apps) → `launchpad recover <slug>`. The bot re-derives reality from live Cloudflare
712
742
  state and repairs the record to `live` only when the app is
713
743
  verifiably serving; if it isn't, it refuses with exactly what was
714
744
  checked — it never fabricates a live state.
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: launchpad-deploy-status
3
3
  description: Show the current provisioning stage + failure reason for a Launchpad app via `launchpad status` (Model A drift + deployment_verified) and `launchpad apps` (lifecycle bucket), or watch provisioning live with `launchpad watch`. Renders the M-892 stage trace for in-flight provisioning, and is the canonical home for `launchpad recover` (repair a terminal-failed app record that is actually live). Use when someone says "what's the status of demo-X", "/launchpad-deploy-status", "is my deploy stuck", "watch my deploy go live", "watch provisioning", "my app says failed but it's serving", or after `/launchpad-deploy` reports a non-`done` terminal stage.
4
- version: 0.77.0
4
+ version: 0.78.0
5
5
  ---
6
6
 
7
7
  <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -70,7 +70,7 @@ inference source resolves.
70
70
  | What was actually deployed? | `launchpad pull --manifest <slug>` |
71
71
  | Is the app stuck in the legacy M-892 zero-touch flow? | See § Legacy below |
72
72
  | What broke the most recent deploy? | `launchpad status <slug> --json` + the bot's PR check trail |
73
- | It says `failed` but the app is live in a browser | `launchpad recover <slug>` — see § Recover below |
73
+ | It says `failed` but the app is live in a browser (a Pages app; `recover` refuses a dispatch app) | `launchpad recover <slug>` — see § Recover below |
74
74
  | A container app is `provisioning_failed` at `deployment_verified` (deploy workflow found its secrets missing; a one-step `launchpad deploy` normally prevents this) | `launchpad secrets push`, then `launchpad recover <slug>`; the bot authorizes and verifies the retry run and marks the app live (watch `launchpad status`) |
75
75
 
76
76
  The Model A default is `launchpad status <slug>` (a one-shot read).
@@ -116,13 +116,18 @@ the canonical reference). Lifecycle-shaped states:
116
116
  To watch it advance to its terminal state live, use
117
117
  `launchpad watch <slug>` (§ Watch).
118
118
  - **`provisioning_failed`** — provisioning failed; the failing stage
119
- and reason are shown inline. If the app is actually live, see
120
- § Recover.
119
+ and reason are shown inline. If the app is actually live and is a Pages
120
+ app, see § Recover; for a failed dispatch app see § First deploy stuck at
121
+ `provisioning_failed`.
121
122
  - **`destroying` / `destroyed` / `destroy_failed`** — teardown
122
123
  states. Route to `/launchpad-destroy`.
123
124
  After a destroy that ends `destroy_failed`, run `launchpad destroy <slug>
124
125
  --confirm-slug <slug> --yes` again; the teardown resumes from the failed
125
- step (a second destroy completed in about 80 s on 16 Nov 2026).
126
+ step (a second destroy completed in about 80 s on 16 Nov 2026). From CLI
127
+ 0.78.0, `launchpad status <slug>` on a `destroy_failed` app shows which
128
+ teardown step failed, the reason the platform recorded, and a next step
129
+ (`--json` adds `failedReason` and `destroyFailure`); an older CLI prints only
130
+ "destroy FAILED".
126
131
 
127
132
  Live-app states:
128
133
 
@@ -180,8 +185,9 @@ field. Common values:
180
185
  - **`failed`** — provisioning failed. See `launchpad status <slug>
181
186
  --json` for the most recent error, and the bot's open PR on
182
187
  `launchpad-platform` for the apply trace. If the app is actually
183
- live and serving, repair the record with `launchpad recover
184
- <slug>` (§ Recover).
188
+ live and serving and is a Pages app, repair the record with
189
+ `launchpad recover <slug>` (§ Recover). For a failed dispatch app see
190
+ § First deploy stuck at `provisioning_failed`.
185
191
  - **`destroying` / `destroyed` / `destroy_failed`** — teardown
186
192
  states. Route to `/launchpad-destroy`.
187
193
  After a destroy that ends `destroy_failed`, run `launchpad destroy <slug>
@@ -231,7 +237,7 @@ Next steps:
231
237
  `live`.
232
238
  ```
233
239
 
234
- Failed deploy:
240
+ Failed deploy (a Pages app; a failed dispatch app gets the destroy-and-deploy-again steps instead of `recover`):
235
241
 
236
242
  ```
237
243
  App: demo-7
@@ -312,8 +318,11 @@ The bootstrap pull request runs CI on the platform's starter files, not on the
312
318
  owner's app, so a failure here is a platform fault. Do not change your
313
319
  lockfile, do not retry, do not use another slug; run `/launchpad-report`. (Run
314
320
  `bun audit` on your own app as good practice only; it does not predict this
315
- check.) The owner cannot retry, resume, abandon, recover or destroy this app;
316
- a platform admin with break-glass rights must purge the slug.
321
+ check.) The owner cannot retry, resume, abandon or recover this app, but CAN
322
+ free the slug with `launchpad destroy` (below). The starter's dependency
323
+ advisories and the audit script are fixed for new apps, so a new failure here
324
+ is unexpected: report it. `launchpad status` may still suggest running `bun
325
+ audit --prod`; that is not the owner's fix.
317
326
 
318
327
  What the user can and cannot do in case (a):
319
328
 
@@ -328,23 +337,29 @@ What the user can and cannot do in case (a):
328
337
  - **`launchpad recover <slug>`**: refuses (409 `not_live`). It repairs only an
329
338
  app that is verifiably serving, and it checks a Pages project that a
330
339
  dispatch app does not have.
331
- - **`launchpad destroy <slug>`**: refuses with `no per-app TF for <slug>`
332
- and tells the user to run `launchpad status` and then `launchpad recover`,
333
- which is circular. The slug stays reserved.
340
+ - **`launchpad destroy <slug> --confirm-slug <slug> --yes`**: works. An owner
341
+ can destroy an app whose first deploy failed at `bot_pr_ci_failed`; it
342
+ releases the slug in seconds (proven on production on 17 Nov 2026 with two
343
+ apps). It archives the app repo and frees the slug; nothing needs deleting by
344
+ hand. Only the owner can run it. An older bot answered 409 `no_per_app_tf`;
345
+ if destroy is refused now, do not retry under another slug and run
346
+ `/launchpad-report` with the slug and the refusal text.
334
347
  - **Operator route.** The runbook (`docs/runbooks/m-892-zero-touch-demo.md`)
335
348
  lists one action for `bot_pr_ci_failed`: "push a fix to the bot PR's branch".
336
349
  That needs write access to the app repo, which an app owner normally does not
337
350
  have, so it is an operator action, not something to offer the user. It also
338
351
  does not restart the stopped provisioning run. On 16 Nov 2026 a fix made
339
352
  every check on the bootstrap PR pass, and the app stayed at
340
- `bot_pr_ci_failed`. A platform admin has to release the slug.
341
- - **Do not create a second slug** to get around it, and do not try to clean up
342
- by hand.
353
+ `bot_pr_ci_failed`. Free the slug with `launchpad destroy` instead.
354
+ - **Do not create a second slug** before the destroy, and do not try to clean
355
+ up by hand.
343
356
 
344
- Say this to the user, then run `/launchpad-report` with the slug and the
345
- `failed` stage and reason text from `launchpad status <slug>`. Ask for
346
- confirmation before filing, as that skill requires. Tell the user the slug
347
- needs the platform team, and not to start a second app meanwhile.
357
+ Say this to the user. Because a bootstrap check failure is a platform fault,
358
+ run `/launchpad-report` with the slug and the `failed` stage and reason text
359
+ from `launchpad status <slug>`, and ask for confirmation before filing, as that
360
+ skill requires. Offer the destroy so the owner can create the app again; if
361
+ the destroy is refused, report that too, and tell the user not to start a
362
+ second app meanwhile.
348
363
 
349
364
  ### (b) `provisioning_failed` at `deployment_verified`: first delivery build failed
350
365
 
@@ -369,8 +384,10 @@ Destroy works in this state (observed twice on 16-17 Nov 2026) and takes about
369
384
  2.5 minutes; if it ends `destroy_failed`, run it again. Fix the cause, then
370
385
  create the app again with `/launchpad-deploy`.
371
386
 
372
- `launchpad recover` does not apply to dispatch apps, even when `launchpad
373
- status` says the app may already be live and suggests it.
387
+ `launchpad recover` does not apply to dispatch apps. From CLI 0.78.0 `launchpad
388
+ status` no longer suggests it for a failed dispatch app: it says to read the
389
+ failed build, fix the cause, run the destroy above and deploy again. An older
390
+ CLI may still print the `recover` line; ignore it.
374
391
 
375
392
  ## Legacy — M-892 stage taxonomy
376
393
 
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: launchpad-destroy
3
3
  description: Tear down a Launchpad app end-to-end via `launchpad destroy` — Cloudflare resources (Pages project, or the dispatch Worker script), 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.
4
- version: 0.77.0
4
+ version: 0.78.0
5
5
  ---
6
6
 
7
7
  <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -125,7 +125,11 @@ Every destroy starts with the same shared steps:
125
125
  There is **no destroy PR and no `destroy:confirmed` label** on this
126
126
  path. Workspace apps live in isolated TF state, so there is no
127
127
  shared apply to pick up a file deletion — teardown is an explicit
128
- `terraform destroy`:
128
+ `terraform destroy`. The CLI's last lines say so: the platform's destroy
129
+ workflow is removing the resources now, with no PR to merge. (An app that never
130
+ got Cloudflare resources, such as a first deploy stopped at `bot_pr_ci_failed`,
131
+ is torn down before any Terraform and the CLI prints `Done:` and that the slug
132
+ is free.)
129
133
 
130
134
  1. The bot fires an **HMAC-signed `repository_dispatch`**
131
135
  (`tf-destroy-per-app`): it signs `<slug>|<exp>` with a secret
@@ -185,10 +189,10 @@ Use the platform runbook `docs/runbooks/d1-destroy-export-restore.md` to recover
185
189
  |---|---|---|
186
190
  | `live` (or absent) | App is operational. | Destroy works. |
187
191
  | `provisioning` | Initial create still running. | Wait, then destroy. |
188
- | `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. |
192
+ | `failed` | Provisioning failed. | Destroy works (cleans up partial state), including a first deploy that failed at `bot_pr_ci_failed`. If a Pages app is actually live and serving, consider `launchpad recover <slug>` first — it repairs the record instead of tearing down. |
189
193
  | `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. |
190
194
  | `destroyed` | Teardown succeeded + repo archive-renamed. | Re-running exits 0 with `already destroyed at <ts>`. The slug remains retired until platform recovery proves live infrastructure. |
191
- | `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). |
195
+ | `destroy_failed` | The teardown failed or hung. | **Workspace path:** re-run `launchpad destroy` — it re-dispatches from the failure point. From CLI 0.78.0, `launchpad status <slug>` shows which teardown step failed, the reason the platform recorded and a next step (`--json`: `failedReason`, `destroyFailure`); an older CLI prints only "destroy FAILED". **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). |
192
196
 
193
197
  ## Carve-outs
194
198
 
@@ -290,13 +294,14 @@ Two cases, both described in `/launchpad-deploy-status` § "First deploy stuck
290
294
  at `provisioning_failed`":
291
295
 
292
296
  - **`bot_pr_ci_failed`** (the bootstrap PR check failed, for example
293
- `npm-audit`): a platform fault, not the owner's lockfile.
294
- `launchpad destroy <slug>` refuses with the `no per-app TF` error (next
295
- section) and says to run `launchpad status` then `launchpad recover`;
296
- `recover` refuses too (`not_live`), so the user cannot clear the slug
297
- themselves. Do not retry in a loop, do not create a second slug, do not
298
- change the lockfile and do not delete anything by hand. A platform admin
299
- must purge the slug; run `/launchpad-report` with the slug.
297
+ `npm-audit`): a platform fault, not the owner's lockfile. The owner CAN
298
+ destroy it: `launchpad destroy <slug> --confirm-slug <slug> --yes` releases
299
+ the slug in seconds (proven on production on 17 Nov 2026 with two apps).
300
+ It archives the app repo; the open bootstrap PR stays on the archived repo.
301
+ `launchpad recover` refuses this app (`not_live`); do not use it. Do not
302
+ create a second slug before the destroy, do not change the lockfile and do
303
+ not delete anything by hand. If the destroy is refused (an older bot answers
304
+ 409 `no_per_app_tf`), run `/launchpad-report` with the slug and the text.
300
305
  - **`deployment_verified`** with `dispatch delivery refused: build-failed`
301
306
  (the bootstrap PR merged, the first delivery build failed):
302
307
  `launchpad destroy <slug> --confirm-slug <slug> --yes` works (observed twice
@@ -314,7 +319,9 @@ main — neither an `apps/<slug>/` workspace nor a `<slug>.tf` +
314
319
  `<slug>.allow.tf` file pair (the bot probes both before this 409).
315
320
  This usually means: (a) the app was never fully provisioned (look
316
321
  at `lifecycle` — likely `failed`), or (b) the TF was hand-removed
317
- outside of this verb. Either way: platform-team intervention.
322
+ outside of this verb. Either way: platform-team intervention. (A first deploy
323
+ stopped at `bot_pr_ci_failed` no longer lands here: its destroy runs the
324
+ pre-Terraform teardown. An older bot still answers this 409.)
318
325
 
319
326
  ### `slug ${urlSlug} is already being destroyed`
320
327
 
@@ -406,7 +413,7 @@ On an idempotent re-run against a `destroyed` slug:
406
413
  - **`/launchpad-deploy-status`** — diagnose `provisioning` /
407
414
  `failed` lifecycle stages. Less relevant after destroy lands.
408
415
  If the app shows `failed` but is actually live and serving, reach
409
- for `launchpad recover <slug>` (documented there) before assuming
416
+ for `launchpad recover <slug>` (documented there; Pages apps only) before assuming
410
417
  destroy + re-create is the fix — recover repairs the registry
411
418
  record against live state. (Recover refuses destroy-side states —
412
419
  `destroying` / `destroyed` / `destroy_failed` are owned by this
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: launchpad-identity
3
3
  description: Teach an app author how to use the signed-in user's identity inside a Launchpad app - read the gateway-forwarded X-Launchpad-User-Assertion in the app's server code (functions/ on a react+api app, compiled into its Worker on dispatch, or a Pages Function on a legacy Pages app), VERIFY it with @m-kopa/platform-auth (fail-closed), and show who's logged in (sub/email/name). Use when someone says "who is logged in", "show the current user", "get the user's email in my app", "auth in my launchpad app", "read the user identity", "/launchpad-identity", or is wiring up an /api/me for a gateway-fronted app.
4
- version: 0.77.0
4
+ version: 0.78.0
5
5
  ---
6
6
 
7
7
  <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: launchpad-ingest
3
3
  description: Scaffold a verified ingest endpoint so an approved backend (an approved integration, ADR 0060) can write into a Launchpad react+api app - declare the integration in launchpad.yaml, add a Hono route registered ahead of the user-auth middleware that verifies the gateway's X-Launchpad-Integration-Assertion with @m-kopa/platform-auth, validates the body with zod, and does an idempotent D1 insert keyed on a caller-supplied idempotency key. Use when someone says "let another system push data into my app", "add an ingest endpoint", "receive data from the Sales backend", "approved integration", "machine-to-machine write", "/launchpad-ingest", or asks what a calling team must send.
4
- version: 0.77.0
4
+ version: 0.78.0
5
5
  ---
6
6
 
7
7
  <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: launchpad-integration-contract
3
3
  description: Design the payload contract for an approved integration (ADR 0060) before anyone writes code - which fields the calling backend sends, which the app sets itself, the idempotency key, how the data lands next to what users already enter, business rules like submission windows, versioning, the allow-list request to the platform team, and the handoff note for the calling team. Use when someone says "design the webhook payload", "what should the other team send us", "agree the contract", "set up the integration with <team>", "what does the platform need to approve this", "allow-list", "/launchpad-integration-contract", or before running /launchpad-ingest on an app that already has its own data.
4
- version: 0.77.0
4
+ version: 0.78.0
5
5
  ---
6
6
 
7
7
  <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: launchpad-onboard
3
3
  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.
4
- version: 0.77.0
4
+ version: 0.78.0
5
5
  ---
6
6
 
7
7
  <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: launchpad-report
3
3
  description: File a bug report or feature request to the Launchpad team's tracker from the CLI. Use when someone reports something broken, hits an error in a launchpad command, or wishes a feature existed — e.g. "this is broken", "report a bug", "can you file that", "I wish launchpad could…", "/launchpad-bug", "/launchpad-feature". Always confirm and show exactly what you'll send before filing; never file silently.
4
- version: 0.77.0
4
+ version: 0.78.0
5
5
  ---
6
6
 
7
7
  <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: launchpad-status
3
3
  description: Safely refresh a Launchpad clone, show manifest drift, or read the deployed manifest. Wraps bare `launchpad pull` for source sync, `launchpad pull --manifest` for deployed YAML, and `launchpad status` for drift. Use for "sync my clone", "what's deployed", "show drift", "/launchpad-status", "/launchpad-pull", or post-deploy verification.
4
- version: 0.77.0
4
+ version: 0.78.0
5
5
  ---
6
6
 
7
7
  <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -163,8 +163,9 @@ The lifecycle states (rendered without needing a local manifest):
163
163
  - **`provisioning_failed`** — the workflow failed; status names the
164
164
  failing stage + reason. Fix the cause and re-run
165
165
  `launchpad deploy` — or, if the app is actually serving despite
166
- the failed record, `launchpad recover <slug>` reconciles the
167
- record against live Cloudflare state.
166
+ the failed record on a Pages app, `launchpad recover <slug>` reconciles the
167
+ record against live Cloudflare state (a failed dispatch app: see
168
+ `/launchpad-deploy-status`; recover refuses it).
168
169
  - **`destroying` / `destroyed` / `destroy_failed`** — teardown
169
170
  phases; route to `/launchpad-destroy`.
170
171
 
@@ -336,8 +337,8 @@ launchpad apps # confirm lifecycle is `live`
336
337
  /launchpad-deploy-status # diagnose the M-892 stage trace
337
338
  ```
338
339
 
339
- If the record says `failed` but the app is actually serving,
340
- `launchpad recover <slug>` reconciles the record against live
340
+ If the record says `failed` but the app is actually serving (a Pages app;
341
+ recover refuses a dispatch app), `launchpad recover <slug>` reconciles the record against live
341
342
  Cloudflare state (it verifies; it never fabricates a live state).
342
343
 
343
344
  ### "drift: hostnames[0]"