@m-kopa/launchpad-cli 0.27.0 → 0.27.2

package/CHANGELOG.md

@@ -6,6 +6,46 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html);
 pre-1.0 minor bumps may carry breaking changes per ADR 0005.
 
+## 0.27.2 — 2026-06-15
+
+Fix: `launchpad login --help` and `launchpad logout --help` (and `-h`)
+now print usage and exit without side effects. Previously both verbs
+ignored their arguments and ran the real flow, so asking for help
+actually signed you in / revoked + cleared your session. The flags are
+now documented on each command's docs page.
+
+## 0.27.1 — 2026-06-12
+
+Bundled-skills refresh (sp-s4k9wm) — no CLI code changes. Every
+`launchpad-*` skill audited claim-by-claim against shipped behaviour
+(141 claims: 43 corrected, 13 coverage gaps filled):
+
+- **Auth guidance** now matches the 0.27.0 gateway login: gateway-first
+  sign-in, the ≤ 0.26.x `launchpad update && launchpad login` recovery,
+  silent rotating-refresh session model (the "~24 h Cf Access session"
+  framing is gone).
+- **`launchpad-content-pr`** reworked to the real deploy model:
+  subsequent deploys commit directly to the app repo's `main` (no
+  content PR), the CLI returns at the bot's 202 ack, and verification
+  is its own `launchpad status` step. The fictional "stack-fit
+  pre-flight" is replaced by the real gates (bundle policy, secret
+  scan, build-command allowlist — delta-judged per ADR 0025).
+- **`launchpad-deploy`** uses `launchpad init`'s real flag vocabulary,
+  documents group displayName|UUID resolution, pages-tier D1
+  (`d1_binding`) auto-provisioning incl. the empty-DB gotcha, and the
+  real server-side gate set.
+- **`launchpad-deploy-status`** carries the full stage taxonomy
+  (`content_seeded`, the `tf_env_*` trio) and folds in
+  `launchpad recover` for terminal-failed-but-serving apps.
+- **`launchpad-status`** documents the full lifecycle/live-truth state
+  union and the live Pages build-outcome rendering.
+- **`launchpad-destroy`** documents the per-app-workspace dispatch
+  teardown (no destroy PR on that path) and that the app's D1 database
+  is never dropped.
+
+Run `launchpad skills update` after upgrading to pick up the refreshed
+bundle.
+
 ## 0.27.0 — 2026-06-12
 
 `launchpad login` moves onto the platform's auth gateway (sp-cli7kq

package/dist/cli.js

@@ -19,7 +19,7 @@ var __toESM = (mod, isNodeMode, target) => {
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/version.ts
-var CLI_VERSION = "0.27.0";
+var CLI_VERSION = "0.27.2";
 
 // src/config.ts
 import * as os from "node:os";
@@ -6724,7 +6724,11 @@ function makeLoginCommand(deps = REAL_DEPS) {
     run: (args, io) => runLogin(args, io, deps)
   };
 }
-async function runLogin(_args, io, deps) {
+async function runLogin(args, io, deps) {
+  if (args.includes("--help") || args.includes("-h")) {
+    printLoginHelp(io);
+    return 0;
+  }
   try {
     const cfg = loadConfig();
     if (cfg.authLegacy) {
@@ -6775,6 +6779,27 @@ async function runLegacyLogin(io, botUrl, sessionPath, deps) {
   io.out(`Access token expires in ~${expiresIn}s; refreshes silently.`);
   return 0;
 }
+function printLoginHelp(io) {
+  io.out("launchpad login — authenticate and store a session.");
+  io.out("");
+  io.out("Usage:");
+  io.out("  launchpad login        Sign in via the browser and store a session");
+  io.out("");
+  io.out("Opens your browser to sign in with your M-KOPA Microsoft account");
+  io.out("through the Launchpad auth gateway (loopback PKCE), then writes the");
+  io.out("session to ~/.launchpad/session.json. The short-lived access token");
+  io.out("refreshes silently as you use the CLI.");
+  io.out("");
+  io.out("Environment:");
+  io.out("  LAUNCHPAD_AUTH_LEGACY=1     Force the legacy Cloudflare Access flow");
+  io.out("                             (deprecated; removed when the dual-auth");
+  io.out("                             window closes)");
+  io.out("  LAUNCHPAD_AUTH_GATEWAY_URL  Override the gateway base URL (testing)");
+  io.out("");
+  io.out("Exit codes:");
+  io.out("  0   signed in / session stored");
+  io.out("  1   login failed (network, browser, or gateway error)");
+}
 function describe19(e) {
   return e instanceof Error ? e.message : String(e);
 }
@@ -6789,7 +6814,11 @@ function makeLogoutCommand(deps = REAL_DEPS2) {
     run: (args, io) => runLogout(args, io, deps)
   };
 }
-async function runLogout(_args, io, deps) {
+async function runLogout(args, io, deps) {
+  if (args.includes("--help") || args.includes("-h")) {
+    printLogoutHelp(io);
+    return 0;
+  }
   try {
     const cfg = loadConfig();
     let session = null;
@@ -6819,6 +6848,22 @@ async function runLogout(_args, io, deps) {
     return 1;
   }
 }
+function printLogoutHelp(io) {
+  io.out("launchpad logout — revoke the session server-side and clear it locally.");
+  io.out("");
+  io.out("Usage:");
+  io.out("  launchpad logout       Revoke server-side, then clear the local session");
+  io.out("");
+  io.out("Gateway (v2) sessions are revoked server-side (the refresh token dies");
+  io.out("immediately; any in-flight access token expires within ~15 minutes),");
+  io.out("then the local ~/.launchpad/session.json is cleared. Logout also works");
+  io.out("offline: if the gateway is unreachable the local session is cleared");
+  io.out("anyway with a warning, and the exit code stays 0.");
+  io.out("");
+  io.out("Exit codes:");
+  io.out("  0   logged out (or already logged out)");
+  io.out("  1   could not clear the local session (file IO / config error)");
+}
 function describe20(e) {
   return e instanceof Error ? e.message : String(e);
 }

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const CLI_VERSION = "0.27.0";
+export declare const CLI_VERSION = "0.27.2";
 //# sourceMappingURL=version.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m-kopa/launchpad-cli",
-  "version": "0.27.0",
+  "version": "0.27.2",
   "description": "Launchpad CLI — clone / deploy / review / merge against Launchpad-managed apps. Talks to the portal-bot endpoints (SCOPE-M-760 / T4).",
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   "homepage": "https://github.com/M-KOPA/launchpad-platform/tree/main/packages/launchpad-cli#readme",
   "license": "UNLICENSED",
   "dependencies": {
-    "esbuild": "0.27.3",
+    "esbuild": "0.28.1",
     "yaml": "2.9.0",
     "zod": "4.4.3"
   },

package/skills/launchpad-content-pr/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: launchpad-content-pr
-description: Push a content change to a Launchpad app via `launchpad deploy` and verify it shipped via `launchpad status`. Covers the post-first-deploy iteration loop (edit → deploy → verify) and the stack-fit pre-flight that the bot enforces server-side. Use when someone says "push a content change", "ship an update", "/launchpad-content-pr", "verify my deploy", or after `/launchpad-deploy` reports `done` and they want to follow up with an edit.
-version: 0.27.0
+description: Push a content change to a Launchpad app via `launchpad deploy` and verify it shipped via `launchpad status`. Covers the post-first-deploy iteration loop (edit → deploy → verify) — subsequent deploys commit directly to the app repo's main and the Pages build runs asynchronously, so verification is its own step. Use when someone says "push a content change", "ship an update", "/launchpad-content-pr", "verify my deploy", or after `/launchpad-deploy` reports `done` and they want to follow up with an edit.
+version: 0.27.2
 ---
 
 <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -33,17 +33,23 @@ esac
 Push a content change to an already-provisioned Launchpad app, then
 verify it shipped.
 
+The slash-command name is historical: subsequent deploys do **not**
+open a content PR any more. The bot commits the bundle **directly to
+the app repo's `main`** and Cloudflare Pages builds from that commit
+asynchronously — so "ship" and "verify" are two separate steps, and
+this skill covers both.
+
 Under Model A the first deploy and the first content are the same
 event — `launchpad init` + `launchpad deploy` from the user's CWD
-opens a PR that contains their working tree, the bot waits for the
-Cloudflare Pages deployment to come up green (`deployment_verified`
-lifecycle gate), and the lifecycle flips to `live`. There is no
-separate "now push content" step.
+stages the working tree with the provisioning run: the workflow's
+`content_seeded` stage commits it straight onto the app repo's
+`main`, the bot waits for the Cloudflare Pages deployment to come up
+green (`deployment_verified`), and the lifecycle flips to `live`.
+There is no separate "now push content" step.
 
 This skill is therefore the **iteration** companion to
 `/launchpad-deploy`: once an app is live, how do you ship the next
-change? It is also the canonical place to find the stack-fit
-pre-flight (the rules the bot enforces server-side on every bundle).
+change — and how do you know it's actually serving.
 
 ## Pre-flight
 
@@ -65,7 +71,10 @@ Look for the slug in the `live` lifecycle bucket. If it's in
 `provisioning` / `failed` / `destroying` / `destroyed`, the
 iteration loop is not the right tool — route to
 `/launchpad-deploy-status` (in-flight) or `/launchpad-destroy`
-(teardown) instead.
+(teardown) instead. If it shows `failed` but the app is actually
+serving (e.g. a verification timed out after the real deploy
+succeeded), `launchpad recover <slug>` reconciles the record against
+live Cloudflare state.
 
 ## Edit and ship
 
@@ -75,92 +84,84 @@ The iteration loop is two verbs:
 # 1. Edit your working tree.
 
 # 2. Ship it.
-launchpad deploy --message "<one-line description>"
+launchpad deploy
 ```
 
-The CLI bundles the CWD (using `git ls-files -co --exclude-standard`
-where available; falling back to a pure-FS walker honouring
-`.gitignore` and a default-ignore set), gzips it, uploads to the
-bot, and the bot opens a content PR on `launchpad-app-<slug>`.
-Cloudflare Pages auto-deploys on merge to `main`; the bot waits for
-the deploy to come up green via the `deployment_verified` lifecycle
-gate before reporting `done`.
-
-Common flags:
-
-- **`--slug <slug>`** — explicit override. Defaults to the slug from
-  `./launchpad.yaml`, or the cwd-name parse if you're in a
-  `launchpad-app-<slug>/` clone.
-- **`--message <text>`** — threaded as the PR description. Useful
-  for change logs and audit trails.
-- **`--file <path>`** — point at a non-default manifest path.
+What happens:
+
+- The CLI bundles the CWD with a **pure-FS walker** (no `git`
+  needed) honouring `.gitignore` plus a default-ignore set; symlinks
+  are never followed. The bundle is gzipped and uploaded to the bot.
+- The bot runs its server-side gates (next section), then commits
+  the bundle **directly to `main`** on `launchpad-app-<slug>` via
+  the Git Data API — you are the commit author, the bot is the
+  committer. No PR, no merge step.
+- The CLI returns at the bot's 202 ack — `✓ Bundle accepted —
+  committed as <sha>`, then "Committed; build pending". It does
+  **not** wait for the Pages build: a successful deploy is **not** a
+  live app yet — the build runs asynchronously and can fail after
+  the commit lands. Always confirm with `launchpad status`.
+
+Flags worth knowing:
+
+- The slug comes from `./launchpad.yaml` (`metadata.slug` /
+  `metadata.name`). On this path `--slug` does **not** override it —
+  it only overrides directory-name inference on the legacy clone
+  flow (no local manifest).
+- **`--message`** is sent as a forward-compat header on the legacy
+  path only, and **the bot currently ignores it**. Don't rely on it
+  for change logs or audit trails.
+- **`--file`** is valid only with `--dry-run` / `--apply`
+  (manifest-driven modes), not with a content deploy.
 
 Exit codes:
 
-- **0** — content PR opened + Cloudflare Pages deployment verified.
-- **non-zero** — see `/launchpad-deploy-status <slug>` for the
-  failure reason.
-
-## Stack-fit — what the bot enforces server-side
-
-The bot rejects bundles that contain shapes the Cloudflare Pages +
-Workers runtime cannot host. The validation runs on every
-`launchpad deploy`; you do not need to pre-flight it locally, but
-**knowing what's enforced saves the round-trip when a bundle is
-going to fail**.
-
-The accepted Launchpad stack is the single source of truth in:
-
-- `launchpad-platform/ARCHITECTURE.md § Tech Stack`
-- `launchpad-platform/PATTERNS.md § Approved Libraries`
-- `launchpad-platform/ANTI-PATTERNS.md`
-
-### Forbidden runtime dependencies
-
-The bot rejects bundles whose `package.json` declares any of these
-runtime dependencies — they do not work in the Workers runtime
-without a non-trivial port:
-
-| Forbidden | Replacement on Launchpad |
-|---|---|
-| `fastify` / `express` / `koa` / `hapi` / `@nestjs/*` | `hono` mounted at `functions/api/[[path]].ts` — the only server framework (PATTERNS.md). |
-| `better-sqlite3` / native `sqlite3` | Cloudflare D1 binding (`wrangler.toml [[d1_databases]]`). |
-| `pg` / `mysql2` / `mongodb` / `mongoose` / `redis` / `ioredis` | Neon (Postgres over HTTP) or another HTTP-driver backend. Native TCP drivers do not work in the Workers runtime. |
-| `dotenv` | `c.env.*` bindings; `wrangler secret put` (or `launchpad envvars` / `launchpad secrets push`) for secrets. |
-| `pm2` / `forever` / `nodemon` | Cloudflare Cron Triggers (`wrangler.toml [triggers] crons`). |
-
-### Forbidden top-level files
-
-The bot rejects bundles whose root contains any of these (on non-
-container app-types):
-
-```
-Dockerfile · docker-compose.yml · docker-compose.yaml · nginx.conf
-pm2.config.js · ecosystem.config.js · Procfile
-```
-
-Their presence is the smoking gun that the app was copied from a
-long-running-server stack without removing the legacy infra.
-
-### Forbidden source patterns
-
-The bot's secret-scan + build-command policy rejects bundles where
-the source tree contains:
-
-- `process.env.X` / `process.env['X']` reads — switch to `c.env.*`
-  bindings.
-- `setInterval` / `setTimeout` daemons — Workers do not run between
-  requests; use Cron Triggers for periodic work.
-- High-signal secret patterns (AWS access keys, GitHub PATs / OAuth
-  / app tokens, Slack tokens, SSH/RSA/EC/PGP keys, generic
-  `api_key` shapes). These never belong in a bundle — push them
-  through `launchpad secrets push` instead.
-
-### `react+api` requires `nodejs_compat`
-
-The bot checks that `wrangler.toml` declares
-`compatibility_flags = ["nodejs_compat"]` for any `react+api` app
-(ADR-0011 carve-out).
+- **0** — bundle accepted and committed (or "nothing to deploy"
+  when `main` already matches the bundle). This is **not** proof the
+  app is live — verify with `launchpad status`.
+- **non-zero** — gate rejections are rendered with per-file detail
+  on stderr; fix the bundle and re-run. For provisioning-phase
+  failures see `/launchpad-deploy-status <slug>`.
+
+## What the bot enforces on every bundle
+
+The canonical gate list and caps live in `/launchpad-deploy
+§ Constants (single source of truth)`. In user-visible terms, every
+upload passes:
+
+- **Bundle policy** — file-count / bundle-size / per-file-size caps,
+  symlink and path-traversal/absolute-path rejection, and auth-file
+  rules (`.github/workflows`, CODEOWNERS, `.npmrc`/`.yarnrc`
+  carrying auth tokens, `.git/`).
+- **Secret scan** — high-signal secret patterns (AWS access keys,
+  GitHub PATs / OAuth / app tokens, Slack tokens, SSH/RSA/EC/PGP
+  private keys, generic `api_key` shapes). These never belong in a
+  bundle — push them through `launchpad secrets push` instead.
+- **Build-command allowlist** — `build.command` must match the
+  bot's allowlist.
+- **App boundary (CLI-side, before upload)** — files outside
+  `app.root` / `app.include` are stripped with a warning, and
+  key/cert-shaped files (`*.pem`, `*.key`, `id_rsa*`, `*.p12`) are
+  denied client-side.
+
+Gates are **delta-judged** (ADR 0025): they evaluate what your
+deploy *changes* relative to `main`, not everything the workspace
+contains. A pre-existing violation already live on `main` becomes a
+non-blocking **standing exception** — recorded by the bot and
+surfaced by both `launchpad deploy` and `launchpad status` (the bot
+serves the inventory at `GET /apps/<slug>/exceptions`). So "my old
+violation didn't block this deploy" is by design, not a missed gate.
+
+There is **no** server-side scan of `package.json` dependencies,
+top-level files, or source patterns. Express/Koa-style servers,
+native DB drivers (`pg`, `better-sqlite3`, …), `dotenv`, and
+pm2/Docker artefacts are not rejected at deploy time — they simply
+won't run on the Cloudflare Pages + Workers runtime and fail at
+build or runtime instead. Likewise `react+api`'s
+`compatibility_flags = ["nodejs_compat"]` in `wrangler.toml`
+(ADR-0011) is **required but not validated** — a missing flag fails
+at runtime. Treat the stack-constraints table in `/launchpad-deploy`
+as advisory architecture guidance, not an enforced gate.
 
 ### Verifying locally before you ship
 
@@ -172,34 +173,47 @@ launchpad validate
 launchpad plan
 ```
 
-Neither verb talks to the bot. Catch what you can locally; the bot
-catches the rest server-side.
+Both are offline by default (no bot). `launchpad validate
+--strict-groups` opts in to an online check that resolves
+`access.allowed_entra_group` (needs a session).
 
-## Verify after merge
+## Verify the deploy
 
 ```bash
 launchpad status <slug>
 ```
 
-Three possible states (see `/launchpad-status` for the canonical
-reference):
-
-- **`in sync`** — local matches deployed; the deploy landed and
-  `deployment_verified` is green. You're done.
-- **`drift: <fields>`** — your local manifest diverges from what was
+`launchpad status` reports manifest drift **and** the live
+Cloudflare Pages build truth — last deployment, what triggered it,
+build outcome, and a failure-log excerpt when the build broke. (See
+`/launchpad-status` for the full state list.) What you're looking
+for after a deploy:
+
+- **`live, in sync`** with `last deployment: build success` — your
+  commit landed and the build is serving. You're done.
+- **`last deployment: build FAILED at stage "<stage>"`** (+ log
+  excerpt) — the commit landed but the build broke; the previous
+  successful deployment is still serving. Fix the cause and re-run
+  `launchpad deploy`.
+- **`build IN PROGRESS`** — re-run `launchpad status` shortly to
+  confirm the outcome.
+- **`drift: <fields>`** — your local manifest diverges from what's
   deployed. Either re-run `launchpad deploy` to ship the local, or
   `launchpad pull <slug> --out launchpad.yaml` to bring the local
   into line with deployed.
-- **`no deployed manifest yet`** — the deploy is still in flight or
-  failed. Re-check in a minute, or run `/launchpad-deploy-status
-  <slug>`.
+- **provisioning / failed / destroy states** — route to
+  `/launchpad-deploy-status` or `/launchpad-destroy`.
+
+Do not declare a change shipped until `status` shows the build
+outcome for your commit.
 
 You can also point a browser at `https://<slug>.launchpad.m-kopa.us`
-once status reports `in sync`. An SSO gate sits in front of the app:
-for a gateway-fronted app (the default, `auth: gateway`) expect a
-redirect to the Entra-OIDC gateway (Microsoft sign-in) on the first
-request; for an `auth: access` app expect a redirect to
-`*.cloudflareaccess.com`. Either way you land on your app after sign-in.
+once status reports the build green. An SSO gate sits in front of
+the app: for a gateway-fronted app (the default, `auth: gateway`)
+expect a redirect to the Entra-OIDC gateway (Microsoft sign-in) on
+the first request; for an `auth: access` app expect a redirect to
+`*.cloudflareaccess.com`. Either way you land on your app after
+sign-in.
 
 If the URL serves the wrong thing:
 
@@ -218,16 +232,23 @@ If the URL serves the wrong thing:
 Once you've shipped first content, the daily-use verbs are:
 
 - **`launchpad status`** (`/launchpad-status`) — is my local
-  `launchpad.yaml` in sync with what's deployed?
+  `launchpad.yaml` in sync with what's deployed, and did the last
+  build succeed?
 - **`launchpad pull <slug>`** (`/launchpad-status`) — read the
   currently-deployed `launchpad.yaml`.
-- **`launchpad deploy`** — package the working tree + open an
-  update PR via the bot.
+- **`launchpad deploy`** — bundle the working tree; the bot commits
+  it directly to the app repo's `main`.
 - **`launchpad envvars`** — list / set / remove non-secret
   production env vars.
-- **`launchpad secrets push`** — push secrets (never via git).
-- **`launchpad logs <slug>`** — recent Cloudflare Pages deployment
-  history.
+- **`launchpad secrets template`** — emit `.env.example` from the
+  manifest's secret bindings.
+- **`launchpad secrets push`** — push secret values from `.env`
+  (never via git).
+- **`launchpad secrets status`** — names-only PRESENT/MISSING audit
+  per binding.
+- **`launchpad logs --slug <slug>`** — recent Cloudflare Pages
+  deployment history (default 10 entries, max 25 via `--lines`).
+  Note: the slug is flag-only, not positional.
 - **`launchpad rollback`** — revert manifest to a prior git SHA +
   re-apply.
 
@@ -237,17 +258,18 @@ Once you've shipped first content, the daily-use verbs are:
   skill. Every step is a `launchpad` verb. External users without
   M-KOPA GitHub access need this skill to work end-to-end on the
   CLI alone.
-- Do **not** open content PRs by hand against the app repo — the
-  bot's bootstrap ruleset gates auto-merge, and a hand-rolled PR
-  bypasses the bundle scan, secret-scan, and build-command policy.
-  Use `launchpad deploy`.
-- Do **not** treat the stack-fit pre-flight as something the user
-  re-implements locally. The bot enforces it server-side on every
-  bundle; the playbook describes what's enforced, not how to
-  re-implement it.
-- Do **not** force-merge if the bot's PR checks are red. The
-  bundle-policy / secret-scan / build-command checks are detecting
-  real things; surface the failure verbatim and let the user fix
+- Do **not** push commits or open PRs by hand against the app repo.
+  The bot commits through a ruleset bypass it alone holds, and a
+  hand-rolled change bypasses the bundle policy, secret-scan,
+  build-command gates, and the standing-exception ledger. Use
+  `launchpad deploy`.
+- Do **not** treat exit 0 from `launchpad deploy` as "live". The
+  commit landed, but the Pages build runs asynchronously and can
+  fail afterwards — always verify with `launchpad status`.
+- Do **not** re-implement the server-side gates locally.
+  `launchpad validate` plus the CLI's own app-boundary pre-flight
+  cover the local half; the bot enforces the rest server-side and
+  renders violations verbatim — surface them and let the user fix
   the bundle.
 - Do **not** edit `launchpad.yaml`'s `production_env:` block to
   contain secret values. That block is non-secret by contract;