@m-kopa/launchpad-cli 0.75.2 → 0.77.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.
Files changed (43) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/dist/bundle/upload.d.ts +16 -0
  3. package/dist/bundle/upload.d.ts.map +1 -1
  4. package/dist/cli.js +2072 -442
  5. package/dist/commands/admin-cli-sessions.d.ts +6 -0
  6. package/dist/commands/admin-cli-sessions.d.ts.map +1 -0
  7. package/dist/commands/admin.d.ts.map +1 -1
  8. package/dist/commands/agreement.d.ts +44 -0
  9. package/dist/commands/agreement.d.ts.map +1 -0
  10. package/dist/commands/app-lints.d.ts +14 -0
  11. package/dist/commands/app-lints.d.ts.map +1 -0
  12. package/dist/commands/deploy.d.ts.map +1 -1
  13. package/dist/commands/disable.d.ts +42 -0
  14. package/dist/commands/disable.d.ts.map +1 -0
  15. package/dist/commands/init.d.ts +8 -0
  16. package/dist/commands/init.d.ts.map +1 -1
  17. package/dist/commands/login.d.ts +4 -1
  18. package/dist/commands/login.d.ts.map +1 -1
  19. package/dist/commands/skills.d.ts +1 -1
  20. package/dist/commands/skills.d.ts.map +1 -1
  21. package/dist/commands/validate.d.ts.map +1 -1
  22. package/dist/dispatcher.d.ts.map +1 -1
  23. package/dist/http/api-client.d.ts +16 -2
  24. package/dist/http/api-client.d.ts.map +1 -1
  25. package/dist/http/error-envelope.d.ts +13 -1
  26. package/dist/http/error-envelope.d.ts.map +1 -1
  27. package/dist/http/errors.d.ts +18 -0
  28. package/dist/http/errors.d.ts.map +1 -1
  29. package/dist/scaffold/secure-api-template.d.ts +57 -0
  30. package/dist/scaffold/secure-api-template.d.ts.map +1 -0
  31. package/dist/version.d.ts +1 -1
  32. package/package.json +2 -2
  33. package/skills/README.md +6 -0
  34. package/skills/launchpad-content-pr/SKILL.md +48 -7
  35. package/skills/launchpad-deploy/SKILL.md +208 -8
  36. package/skills/launchpad-deploy-status/SKILL.md +88 -3
  37. package/skills/launchpad-destroy/SKILL.md +29 -3
  38. package/skills/launchpad-identity/SKILL.md +31 -1
  39. package/skills/launchpad-ingest/SKILL.md +15 -7
  40. package/skills/launchpad-integration-contract/SKILL.md +276 -0
  41. package/skills/launchpad-onboard/SKILL.md +21 -1
  42. package/skills/launchpad-report/SKILL.md +1 -1
  43. package/skills/launchpad-status/SKILL.md +8 -1
@@ -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.75.2
4
+ version: 0.77.0
5
5
  ---
6
6
 
7
7
  <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -71,6 +71,15 @@ Catalogue listing controls discovery only.
71
71
  It neither grants access nor makes an app private.
72
72
  Platform-admin entry is independent of app groups, ownership and listing, and does not assign app-specific business roles.
73
73
 
74
+ ## Access agreement
75
+
76
+ Every person who deploys must accept the Launchpad access agreement once a year.
77
+ If a command stops with exit code `43` or `agreement_required`, or `launchpad login` says the agreement needs accepting, stop.
78
+ Tell the human to read it (`launchpad agreement show`) and to run `launchpad agreement accept` themselves in their own terminal.
79
+ Never type the acceptance phrase, never pipe input into `accept`, and never claim the human accepted.
80
+ An AI agent may not accept the agreement for a person.
81
+ `launchpad destroy` is never blocked by the agreement.
82
+
74
83
  ## Constants (single source of truth)
75
84
 
76
85
  These values are referenced by `/launchpad-deploy-status`,
@@ -236,6 +245,17 @@ against an existing file is rejected unless `--force` is passed —
236
245
  the manifest is the user's authored artefact, the CLI does not
237
246
  silently overwrite it.
238
247
 
248
+ **What `init` does not create.** `launchpad init` writes `./launchpad.yaml`
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.)
258
+
239
259
  **Stack constraints by app-type** (single source of truth:
240
260
  `launchpad-platform/ARCHITECTURE.md § Tech Stack` and `PATTERNS.md §
241
261
  Approved Libraries`). Surface this table to the user **before** they
@@ -260,6 +280,90 @@ the existing app uses any of these, plan the swap **before** picking
260
280
  a slug — do not deploy first and port later. What the bot *does*
261
281
  enforce at deploy time is the gate set in §A.5.
262
282
 
283
+ ### A.2b React API app: the proven recipe
284
+
285
+ 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.
289
+
290
+ **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
+ that imports `hono` and `@m-kopa/platform-auth`. The first delivery build
295
+ compiles it, so if the owner's `package.json` lacks those two dependencies the
296
+ build fails with `Could not resolve "hono/cloudflare-pages"` and the app ends
297
+ `provisioning_failed` at `deployment_verified`.
298
+
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:
323
+
324
+ ```bash
325
+ npx --yes bun@1.3.4 install --frozen-lockfile --ignore-scripts
326
+ npx --yes bun@1.3.4 x tsc --noEmit
327
+ npx --yes bun@1.3.4 run test
328
+ npx --yes bun@1.3.4 run build
329
+ npx --yes wrangler@4.136.3 pages functions build functions --outdir "$(mktemp -d)" --compatibility-date 2026-07-27 --compatibility-flags nodejs_compat
330
+ ```
331
+
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
342
+ ships the content; do not deploy again to check.
343
+
344
+ Two traps (observed on 16-17 Nov 2026):
345
+
346
+ - **Hidden files in the build output** (step 4).
347
+ - **A global `~/.npmrc` that routes `@m-kopa` to another registry** (for
348
+ example GitHub Packages) can make the install 404 for
349
+ `@m-kopa/platform-auth`, which is on the public npm registry. Put one line
350
+ in a project `.npmrc`: `@m-kopa:registry=https://registry.npmjs.org`. Never
351
+ put a token in it; the bot rejects a bundle whose `.npmrc` carries auth.
352
+
353
+ **bun version.** The template workflows build with bun 1.3.4
354
+ (`bun-version: "1.3.4"`). A lockfile written by bun 1.4 or newer has
355
+ `"lockfileVersion": 2`, which bun 1.3.4 cannot read: the first delivery build
356
+ fails at "Install dependencies" with `Unknown lockfile version`, and the app
357
+ ends `provisioning_failed` at `deployment_verified`. Check before deploying:
358
+
359
+ ```bash
360
+ bun --version
361
+ grep lockfileVersion bun.lock
362
+ ```
363
+
364
+ The second line must show `"lockfileVersion": 1`. If it shows 2, regenerate
365
+ with `npx --yes bun@1.3.4 install`.
366
+
263
367
  ### A.3 Deliberately share with an Entra group
264
368
 
265
369
  The CLI resolves Entra groups via the bot's `/groups` endpoint
@@ -299,7 +403,9 @@ Never use the assigned `groups list` shortlist as identity or drift authority.
299
403
  --strict-groups`, `launchpad groups resolve <name|uuid>`, and
300
404
  `launchpad deploy --dry-run` all resolve against the **whole tenant**
301
405
  (PS-1859), so any of them correctly accepts a valid unassigned group.
302
- Use whichever fits; `--dry-run` additionally previews the Terraform.
406
+ Use whichever fits; `--dry-run` additionally previews the Terraform, but it
407
+ needs a git repository with at least one commit (a fresh `launchpad init`
408
+ folder has none).
303
409
 
304
410
  This `--group` flow sets the group at first deploy.
305
411
  Changing groups on an existing app still uses a plain `launchpad deploy`.
@@ -336,8 +442,8 @@ they want to confirm they'll still be able to reach it.
336
442
  launchpad validate
337
443
  ```
338
444
 
339
- Parses `launchpad.yaml` against the v1alpha1 schema and reports
340
- problems. Doesn't talk to the bot by default. Useful when the user
445
+ Parses `launchpad.yaml` and reports problems (it accepts both the v1alpha1
446
+ and the v2 manifest). Doesn't talk to the bot by default. Useful when the user
341
447
  wants a second look before paying for an upload round-trip.
342
448
 
343
449
  Add `--strict-groups` to *additionally* resolve the manifest's
@@ -349,12 +455,46 @@ network (exit 1 = group not found / ineligible / ambiguous,
349
455
  2 = network error, 3 = no valid session **or the caller is not an
350
456
  employee** — the tenant resolve is employee-gated).
351
457
 
458
+ `launchpad plan` and `launchpad generate` read only the v1alpha1 manifest.
459
+ The v2 manifest that `launchpad init` writes (`apiVersion: launchpad.m-kopa.us/v2`,
460
+ a `spec:` block) makes both fail with `Unrecognized key: spec`, although the
461
+ manifest is fine. For a v2 manifest use `launchpad validate`, and
462
+ `launchpad deploy --dry-run` to preview (it needs a git repository with at
463
+ least one commit: run `git init` and commit first, or it fails with "failed to
464
+ resolve git HEAD"). Do not "fix" the manifest to satisfy
465
+ `plan`, and do not rewrite it as v1.
466
+
467
+ **Declaring env vars and secrets (v2 / dispatch app).** Add them to the
468
+ manifest under `spec.env_vars`; the key must be `UPPER_SNAKE_CASE`, and each
469
+ entry is either a plain value or a secret reference:
470
+
471
+ ```yaml
472
+ spec:
473
+ env_vars:
474
+ GREETING:
475
+ type: plain_text
476
+ value: hello
477
+ DEMO_TOKEN:
478
+ type: secret_text
479
+ secret_ref: demo-token
480
+ ```
481
+
482
+ A name ending `_TOKEN` or `_SECRET` must be `secret_text`. Put the secret's
483
+ value in `.env` as `DEMO_TOKEN=<value>`, deploy, and once `launchpad status`
484
+ shows the first delivery push it (the value goes to the dispatch Worker and is
485
+ live at once, with no redeploy), then check that it is set:
486
+
352
487
  ```bash
353
- launchpad plan
488
+ launchpad secrets push --yes
489
+ launchpad secrets status
354
490
  ```
355
491
 
356
- Same, but also summarises what the manifest would deploy: hostnames,
357
- build command, destination directory, allowed group. Still offline.
492
+ If the values are in a file other than `.env`, use `launchpad secrets push
493
+ --env <file> --yes` (`--env` is a documented flag; observed on 17 Nov 2026,
494
+ `--help` is not supported). `secrets status` lists names only
495
+ (PRESENT/MISSING). The manifest never holds the value. `launchpad envvars set` is for Pages apps only: on an app
496
+ managed through the manifest it changes nothing and prints this route.
497
+ `launchpad secrets template` writes `.env.example` from the declared names.
358
498
 
359
499
  ### A.5 Deploy
360
500
 
@@ -368,7 +508,12 @@ plus a built-in default-ignore set — it never shells out to
368
508
  gzips it, and POSTs to the bot's `/apps/<slug>/deploy/bundle`
369
509
  endpoint. Files outside the manifest's app boundary (`app.root` /
370
510
  `app.include`) and never-shippable files (private keys, `.env`
371
- material) are stripped with a warning before upload.
511
+ material) are stripped with a warning before upload. The default
512
+ `app.include` that `launchpad init` writes covers the lockfiles, `package.json`,
513
+ `tsconfig*.json`, `vite.config.*`, `src/**` and `public/**` (plus `functions/**`
514
+ for `react+api`); it leaves out lint config (`eslint.config.*`) and tests
515
+ (`test/**`, `vitest.config.*`). Add them to `spec.app.include` when the app's
516
+ CI needs them.
372
517
 
373
518
  ### Container apps — use `auth: gateway` (AIO-811)
374
519
 
@@ -435,6 +580,50 @@ fresh slug auto-provisions:
435
580
  Confirm the deployed commit and successful build with `launchpad status <slug>`.
436
581
  A merged commit alone does not prove delivery on either origin.
437
582
 
583
+ **First deploy: what to expect and what to check.**
584
+
585
+ - **Time.** Expect 5-10 minutes from the bot accepting the deploy to `live`
586
+ (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.
588
+ - **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:
591
+
592
+ ```bash
593
+ launchpad watch <slug>
594
+ ```
595
+
596
+ and, for a one-shot read, `launchpad status <slug>`. Only `live` (and for
597
+ dispatch, `v2 delivery: state delivered`) is done.
598
+ - **HTTP 503 `gateway_capacity_unavailable`** ("Gateway capacity could not be
599
+ verified. No app was created.") on a first deploy: nothing was created, so
600
+ nothing needs cleaning up. Wait 30 seconds and run the same `launchpad
601
+ deploy` again. Each attempt itself takes about 30 seconds. After 7 failed
602
+ attempts stop and run `/launchpad-report` with the slug and the error text;
603
+ never switch to another slug. A fix for this fault is in review.
604
+ `503 enforced_access_unavailable` ("cannot verify enforced access from
605
+ Terraform - retry shortly") is a retryable 503 too: same wait, same limit.
606
+ 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.**
608
+ The bot's bootstrap pull request runs CI (the `launchpad-review` workflow) on
609
+ the platform's starter files, not on your app. If it fails (for example
610
+ `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.
614
+
615
+ What the bootstrap CI runs on the first PR, on the starter files (jobs `lint`,
616
+ `typecheck`, `test`, `gitleaks`, `npm-audit`):
617
+ - install with `bun install --frozen-lockfile`, so a committed `bun.lock`
618
+ that matches `package.json` is required;
619
+ - lint (`eslint .`), so the app needs an ESLint config;
620
+ - typecheck (`tsc --noEmit`) and test (`bun run test`), so the app needs a
621
+ `tsconfig.json` and a `test` script in `package.json`;
622
+ - the secret scan (`gitleaks`) and `bun audit`.
623
+
624
+ Your own files are built later, by the first delivery build (`launchpad-build`),
625
+ which installs with bun 1.3.4 and compiles `functions/`; see §A.2b.
626
+
438
627
  **What the bot enforces at deploy time** (the real gate set — there
439
628
  is no dependency/stack-fit gate, see §A.2):
440
629
 
@@ -496,6 +685,17 @@ Flags — there is nothing useful to pass on the Model A path:
496
685
  symlinks, secret-pattern hits, build-command violations) are
497
686
  rejected at upload and self-describing in the CLI's stderr; surface
498
687
  them verbatim and let the user fix and re-`launchpad deploy`.
688
+ - **First deploy ended `provisioning_failed` / `bot_pr_ci_failed`** (for
689
+ 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
691
+ loop `deploy`, `recover`, `--resume`, `--abandon` or `--allow-unguarded`:
692
+ none of them clears it. Follow `/launchpad-deploy-status` § "First deploy
693
+ stuck at `provisioning_failed`" and run `/launchpad-report` with the slug.
694
+ - **First deploy ended `provisioning_failed` at `deployment_verified`** with
695
+ `dispatch delivery refused: build-failed` (the bootstrap PR merged, the first
696
+ delivery build failed) → follow `/launchpad-deploy-status` § "First deploy
697
+ failed at `deployment_verified`". Do not use `launchpad recover`: it does not
698
+ apply to dispatch apps even when `launchpad status` suggests it.
499
699
  - **Dispatch delivery refused** (`launchpad status` shows `v2 delivery:
500
700
  state refused`) → surface the `failed at` reason verbatim. For
501
701
  `hidden build output is not supported`, follow the fix in §A.2 and
@@ -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.75.2
4
+ version: 0.77.0
5
5
  ---
6
6
 
7
7
  <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -120,6 +120,9 @@ the canonical reference). Lifecycle-shaped states:
120
120
  § Recover.
121
121
  - **`destroying` / `destroyed` / `destroy_failed`** — teardown
122
122
  states. Route to `/launchpad-destroy`.
123
+ After a destroy that ends `destroy_failed`, run `launchpad destroy <slug>
124
+ --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).
123
126
 
124
127
  Live-app states:
125
128
 
@@ -181,6 +184,9 @@ field. Common values:
181
184
  <slug>` (§ Recover).
182
185
  - **`destroying` / `destroyed` / `destroy_failed`** — teardown
183
186
  states. Route to `/launchpad-destroy`.
187
+ After a destroy that ends `destroy_failed`, run `launchpad destroy <slug>
188
+ --confirm-slug <slug> --yes` again; the teardown resumes from the failed
189
+ step (a second destroy completed in about 80 s on 16 Nov 2026).
184
190
 
185
191
  Restrict to a single slug with `grep` if the list is long —
186
192
  `launchpad apps` has no `--json` flag, so the table is the only
@@ -262,6 +268,8 @@ from inside the app directory.
262
268
 
263
269
  What it does (bot `POST /apps/<slug>/recover`):
264
270
 
271
+ - **Pages apps (and containers) only.** It checks a Pages project, so on a
272
+ dispatch app it answers `not_live`; use `launchpad status` instead.
265
273
  - **Re-derives reality from the live Cloudflare Pages API** — never
266
274
  TF state, never the stale record. The record is repaired (flipped
267
275
  to `live`) only when the Pages project exists and a successful
@@ -289,6 +297,81 @@ strictly after live verification. It never touches Cloudflare
289
297
  resources, the app repo, or TF. After a repair, re-run `launchpad
290
298
  status <slug>` — it then reports the live deployment truth.
291
299
 
300
+ ## First deploy stuck at `provisioning_failed` / `bot_pr_ci_failed`
301
+
302
+ A brand-new slug whose FIRST deploy failed shows `launchpad status <slug>` as
303
+ `provisioning_failed` (lifecycle `failed`). There are two different cases; read
304
+ the stage and reason, then use the matching route. Time expectations: the CLI
305
+ waits about 480 s, and a first deploy to `live` took about 8 to 9 minutes in
306
+ three runs on 16-17 Nov 2026.
307
+
308
+ ### (a) `bot_pr_ci_failed`: the bootstrap PR check failed
309
+
310
+ Example: `bot_pr_ci_failed: bootstrap PR #1 CI failed: failed checks: npm-audit`.
311
+ The bootstrap pull request runs CI on the platform's starter files, not on the
312
+ owner's app, so a failure here is a platform fault. Do not change your
313
+ lockfile, do not retry, do not use another slug; run `/launchpad-report`. (Run
314
+ `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.
317
+
318
+ What the user can and cannot do in case (a):
319
+
320
+ - **Cannot re-run it.** `launchpad deploy` from the same folder stops with
321
+ "no trusted source baseline"; `pull --bootstrap` is for legacy clones only.
322
+ `launchpad deploy --allow-unguarded` meets a 503 `enforced_access_unavailable`.
323
+ Do not loop on any of these.
324
+ - **`launchpad deploy --resume <slug>`**: by design the bot refuses a resume
325
+ from `bot_pr_ci_failed` (409 `not_resumable`; only `tf_apply_failed` is
326
+ resumable). On 16 Nov 2026 `--resume` and `--abandon` both answered "app not
327
+ found (or you have no access)" for such an app. Neither frees the slug.
328
+ - **`launchpad recover <slug>`**: refuses (409 `not_live`). It repairs only an
329
+ app that is verifiably serving, and it checks a Pages project that a
330
+ 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.
334
+ - **Operator route.** The runbook (`docs/runbooks/m-892-zero-touch-demo.md`)
335
+ lists one action for `bot_pr_ci_failed`: "push a fix to the bot PR's branch".
336
+ That needs write access to the app repo, which an app owner normally does not
337
+ have, so it is an operator action, not something to offer the user. It also
338
+ does not restart the stopped provisioning run. On 16 Nov 2026 a fix made
339
+ 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.
343
+
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.
348
+
349
+ ### (b) `provisioning_failed` at `deployment_verified`: first delivery build failed
350
+
351
+ Example: `dispatch delivery refused: build-failed`. The bootstrap PR merged, and
352
+ the first delivery build (workflow `launchpad-build`) failed on the owner's
353
+ files. The usual causes are a lockfile written by bun 1.4 or newer
354
+ (`Unknown lockfile version`), a missing `hono` or `@m-kopa/platform-auth`
355
+ dependency, or hidden files in the build output; see `/launchpad-deploy`
356
+ §A.2b. The route:
357
+
358
+ ```bash
359
+ gh run view <id> -R M-KOPA/launchpad-app-<slug> --log-failed
360
+ ```
361
+
362
+ Read the failed job to find the cause, then free the slug:
363
+
364
+ ```bash
365
+ launchpad destroy <slug> --confirm-slug <slug> --yes
366
+ ```
367
+
368
+ Destroy works in this state (observed twice on 16-17 Nov 2026) and takes about
369
+ 2.5 minutes; if it ends `destroy_failed`, run it again. Fix the cause, then
370
+ create the app again with `/launchpad-deploy`.
371
+
372
+ `launchpad recover` does not apply to dispatch apps, even when `launchpad
373
+ status` says the app may already be live and suggests it.
374
+
292
375
  ## Legacy — M-892 stage taxonomy
293
376
 
294
377
  The provisioning workflow (Model A first deploys and the legacy
@@ -329,8 +412,10 @@ and `launchpad status <slug> --json` (the most recent transition).
329
412
  You no longer parse the bot's `/apps/<sub>/status` shape by hand
330
413
  from the playbook — every status surface goes through the CLI.
331
414
 
332
- If a legacy app is genuinely stuck mid-pipeline (e.g. a bot PR
333
- failed CI), the recovery paths are:
415
+ If a legacy app is genuinely stuck mid-pipeline, the recovery paths
416
+ below apply to `tf_apply_failed` and the legacy zero-touch flow only. A first
417
+ deploy that stopped at `bot_pr_ci_failed` is not resumable: see "First deploy
418
+ stuck at `provisioning_failed`" above. The paths are:
334
419
 
335
420
  - **Resume:** `launchpad deploy --resume <slug>` — re-fires the bot
336
421
  endpoint and walks the stages again from where they failed.
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: launchpad-destroy
3
- 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.
4
- version: 0.75.2
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
5
5
  ---
6
6
 
7
7
  <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -31,7 +31,9 @@ esac
31
31
  # /launchpad-destroy
32
32
 
33
33
  Destructive, owner-only verb. Tears down a Launchpad app end-to-end:
34
- the Cloudflare Pages project, the app's edge-auth wiring (gateway
34
+ the app's Cloudflare resources (the Pages project on a Pages app; the Worker
35
+ script in the dispatch namespace on a dispatch app, which has no Pages project),
36
+ the app's edge-auth wiring (gateway
35
37
  KV/audience entries for gateway-fronted apps — the default; the
36
38
  Access app for `auth: access` apps), custom hostname,
37
39
  launchpad-platform TF, and the app repo (archive-renamed, not
@@ -146,6 +148,11 @@ shared apply to pick up a file deletion — teardown is an explicit
146
148
  `destroy_failed`, repo untouched; re-running `launchpad destroy`
147
149
  re-dispatches the teardown.
148
150
 
151
+ A destroy takes about 2.5 minutes. If it ends `destroy_failed`, run `launchpad destroy <slug>
152
+ --confirm-slug <slug> --yes` again; the teardown resumes from the failed
153
+ step. Verified on 16 Nov 2026: a destroy ended `destroy_failed` although the
154
+ Terraform destroy had passed, and a second destroy completed in about 80 s.
155
+
149
156
  ### Legacy file-pair path (shared-root apps only)
150
157
 
151
158
  Still shipped, for apps whose TF is the shared-root `<slug>.tf` +
@@ -277,6 +284,25 @@ destroy. Either:
277
284
  - Get break-glass access from platform-team for this specific
278
285
  destroy (audited; one-shot).
279
286
 
287
+ ### A first deploy that failed (`provisioning_failed`)
288
+
289
+ Two cases, both described in `/launchpad-deploy-status` § "First deploy stuck
290
+ at `provisioning_failed`":
291
+
292
+ - **`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.
300
+ - **`deployment_verified`** with `dispatch delivery refused: build-failed`
301
+ (the bootstrap PR merged, the first delivery build failed):
302
+ `launchpad destroy <slug> --confirm-slug <slug> --yes` works (observed twice
303
+ on 16-17 Nov 2026) and takes about 2.5 minutes. If it ends `destroy_failed`,
304
+ run it again. Fix the cause first (see `/launchpad-deploy-status`).
305
+
280
306
  ### `<slug> is pre-M-1182 main.tf-resident`
281
307
 
282
308
  See "Carve-outs". Platform-team manual cleanup is required.
@@ -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.75.2
4
+ version: 0.77.0
5
5
  ---
6
6
 
7
7
  <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -121,6 +121,23 @@ the source of truth. If they ever disagree, the contract doc wins.
121
121
  one audience across apps, a token minted for app A is **replayable** against
122
122
  app B (cross-app token replay). Audience-pinning is what stops that.
123
123
 
124
+ ## Which example is for which app shape
125
+
126
+ - **`react+api` app built from the platform starter (the normal dispatch
127
+ case).** The seeded `functions/api/[[path]].ts` is a Hono router that already
128
+ has an auth middleware (`createPlatformAuthMiddleware` from
129
+ `@m-kopa/platform-auth/hono`) and an `/api/me`-style route. Edit that route:
130
+ do not add a second `functions/api/me.js`, which would be a competing route.
131
+ The starter route returns `preferredUsername`, `sub` and `groups`; change it
132
+ to return only what the app needs (`sub`, email, name), and do not return
133
+ `groups` unless the app needs them. An unauthenticated request never gets an
134
+ anonymous 200 body: the middleware answers 401 (or the gateway answers a 302
135
+ to the sign-in page first). Observed on 17 Nov 2026 with an unauthenticated
136
+ client; not checked with a signed-in user. See `/launchpad-deploy` §A.2b.
137
+ - **Legacy Pages app (or any app whose own `functions/` file is a Pages
138
+ handler).** Use the `functions/api/me.js` example below, which returns an
139
+ anonymous shape when the token is missing and verifies it itself.
140
+
124
141
  ## The canonical handler - `functions/api/me.js`
125
142
 
126
143
  Lifted from the **deployed-and-verified** peoplemgr app
@@ -215,6 +232,12 @@ What the verified `user` carries (from the contract doc):
215
232
  > gateway's **login-time snapshot**; never make an access decision from these
216
233
  > values. Enforce authorization at the gateway (allowed groups) and
217
234
  > server-side, not from `/api/me`.
235
+ >
236
+ > The one exception is `requireRole` in the `launchpad init --secure-template`
237
+ > scaffold. It reads `groups` from the **verified** assertion for coarse roles
238
+ > (writer, admin) and accepts the snapshot lag: removing someone from a role
239
+ > group takes effect at their next gateway sign-in. When revocation must be
240
+ > immediate, look the role up server-side instead.
218
241
 
219
242
  ## Reading it from the client
220
243
 
@@ -414,6 +437,13 @@ An unverified payload can be forged by anyone who can reach your origin
414
437
  `launchpad redeploy` if you added them after the last one.
415
438
  - [ ] `aud` is your **bare host** (`<slug>.launchpad.m-kopa.us`), no scheme/port.
416
439
  - [ ] No authorization decision is made from `/api/me` — attribution only.
440
+ - [ ] Every route that changes data checks the caller's role server-side
441
+ (a new `react+api` app can start from `launchpad init --secure-template`).
442
+ - [ ] If the app keeps its own session (a cookie it mints), the session lasts
443
+ **1 hour or less**, or the assertion is re-verified on every request.
444
+ - [ ] `launchpad validate --app-lints` reports no `route-without-auth` or
445
+ `assertion-*` findings (report only today; the platform plans to run the
446
+ same rules at deploy).
417
447
 
418
448
  ## Don'ts
419
449
 
@@ -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.75.2
4
+ version: 0.77.0
5
5
  ---
6
6
 
7
7
  <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -54,15 +54,22 @@ Add it to `launchpad.yaml`.
54
54
  The path is an **exact match**: no prefixes, query strings, `%` escapes or trailing `/`.
55
55
  Methods are a subset of `POST`, `PUT`, `PATCH`, `DELETE`.
56
56
 
57
+ A v2 manifest (what `launchpad init` writes) takes it **under `spec:`**; a
58
+ top-level `integrations:` key fails `launchpad validate` with
59
+ `Unrecognized key`. Only a v1alpha1 manifest puts it at the top level.
60
+
57
61
  ```yaml
58
- integrations:
59
- - name: sales-backend
60
- path: /api/ingest/stock-count
61
- methods: [POST]
62
+ spec:
63
+ integrations:
64
+ - name: sales-backend
65
+ path: /api/ingest/stock-count
66
+ methods: [POST]
62
67
  ```
63
68
 
64
69
  ## Step 2 - create the table
65
70
 
71
+ If the data has to sit next to rows your users already write, add columns to that table instead; `/launchpad-integration-contract` Step 1 shows how.
72
+ This fresh table is for data no existing screen reads.
66
73
  The idempotency key is the primary key, so a replayed request can never add a second row.
67
74
  Add this as a D1 migration (for example `migrations/0001_stock_counts.sql`).
68
75
 
@@ -236,7 +243,7 @@ If you genuinely cannot (for example a build-less app with no `package.json`), y
236
243
  |---|---|
237
244
  | signature | RS256 against the gateway JWKS (`https://auth.launchpad.m-kopa.us/.well-known/jwks.json`). No other algorithm. |
238
245
  | `iss` | `GATEWAY_ISSUER` (`https://auth.launchpad.m-kopa.us`) |
239
- | `aud` | `"integration:" + GATEWAY_AUD`, for example `integration:wh-count.launchpad.m-kopa.us` |
246
+ | `aud` | `"integration:" + GATEWAY_AUD`, for example `integration:shelf-check.launchpad.m-kopa.us` |
240
247
  | `typ` | `launchpad-integration` |
241
248
  | `sub` | starts with `integration:`; the rest is the integration name, which must be yours |
242
249
  | `htm` | the request method, upper case |
@@ -263,10 +270,11 @@ Hand the calling team this contract:
263
270
  - **Never retry other `4xx`.**
264
271
  `401` means a wrong, revoked or unapproved key or route; `403` means a wrong integration or a blocked IP; `400` means a bad body.
265
272
  Retrying won't fix any of them.
273
+ The one exception is a `409` the contract names as resendable later, such as a closed window; see `/launchpad-integration-contract` Step 4.
266
274
 
267
275
  ## Checklist before you ship
268
276
 
269
- - [ ] `integrations:` declared in `launchpad.yaml` with the exact path the handler serves.
277
+ - [ ] `integrations:` declared in `launchpad.yaml` (under `spec:` on a v2 manifest) with the exact path the handler serves.
270
278
  - [ ] Ingest route registered **before** the user-auth middleware.
271
279
  - [ ] `verifyIntegrationAssertion` gets the host from `GATEWAY_AUD` (never the request URL), the request method, and `new URL(c.req.url).pathname`.
272
280
  - [ ] The returned name is checked against your integration.