@m-kopa/launchpad-cli 0.26.1 → 0.27.1

package/skills/launchpad-status/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: launchpad-status
 description: Show whether a Launchpad app's local launchpad.yaml matches what's deployed, and read the deployed manifest. Wraps `launchpad pull` (fetch deployed YAML) and `launchpad status` (drift report). Use when someone says "is my app in sync", "what's deployed", "show drift", "/launchpad-status", "/launchpad-pull", or after `launchpad deploy` to verify the change landed.
-version: 0.26.1
+version: 0.27.1
 ---
 
 <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -34,7 +34,11 @@ Read-only verbs. Zero local platform-repo / terraform / GitHub
 credentials needed. Both go through the bot's `/manifest/state`
 endpoint; the bot reads launchpad-platform's TF state to find the
 last-applied manifest sha, then fetches launchpad.yaml from the app
-repo at that sha. The CLI is a thin client.
+repo at that sha. `launchpad status` additionally reads the bot's
+`/apps/<slug>/lifecycle`, `/apps/<slug>/deployment-status` and
+`/apps/<slug>/exceptions` surfaces, so it reports the **live**
+Cloudflare Pages build truth — not just the manifest view. The CLI
+is a thin client.
 
 ## When to use which verb
 
@@ -54,7 +58,7 @@ the answer.
 
 ## Pre-flight
 
-Both verbs need a current Cf Access session. If `~/.launchpad/session.json`
+Both verbs need a current session (`launchpad login`). If the session
 is missing or expired, surface the run-login hint:
 
 ```bash
@@ -99,6 +103,9 @@ launchpad pull horizon --out /tmp/deployed.yaml
 launchpad clone horizon
 cd launchpad-app-horizon
 launchpad pull
+
+# Read the role-redacted status block instead of the spec manifest
+launchpad pull horizon --status
 ```
 
 Exit codes:
@@ -111,22 +118,75 @@ Exit codes:
 Reads `./launchpad.yaml` by default, compares to the deployed
 manifest, reports state.
 
-### Three possible states
+### The state union
+
+`launchpad status` is lifecycle-aware: it reports one of a closed
+union of states, not just a drift verdict. The drift pair:
 
-- **`in sync`** — local and deployed are equivalent. The
-  equivalence relation is normalised-AST: whitespace, comments, and
-  key ordering do NOT count as drift. Schema defaults are honoured
-  (absent key with a default == explicit default).
+- **`in sync`** (`in_sync` in `--json`) — local and deployed are
+  equivalent. The equivalence relation is normalised-AST:
+  whitespace, comments, and key ordering do NOT count as drift.
+  Schema defaults are honoured (absent key with a default ==
+  explicit default).
 - **`drift: <field list>`** — local and deployed differ on at least
   one field in the v1 closed set:
   `metadata.name`, `metadata.team`, `metadata.owner`,
   `metadata.description`, `deployment.type`,
   `access.allowed_entra_group`, `hostnames[0]`, `build.command`,
   `build.destination_dir`, `build.root_dir`, `production_env.*`.
-- **`no deployed manifest yet`** — bot reports no
-  `output "<slug>_manifest_sha"`. Run `launchpad deploy` first.
 
-### Three-state surfacing
+The lifecycle states (rendered without needing a local manifest):
+
+- **`provisioning`** — the provisioning workflow is running; status
+  shows the current stage inline. Re-run to watch progress.
+- **`provisioning_failed`** — the workflow failed; status names the
+  failing stage + reason. Fix the cause and re-run
+  `launchpad deploy` — or, if the app is actually serving despite
+  the failed record, `launchpad recover <slug>` reconciles the
+  record against live Cloudflare state.
+- **`destroying` / `destroyed` / `destroy_failed`** — teardown
+  phases; route to `/launchpad-destroy`.
+
+And the live-truth states:
+
+- **`live_no_content`** — provisioned but nothing deployed yet. Run
+  `launchpad deploy`.
+- **`live_content_untracked`** — the app IS live, but content
+  reached Cloudflare Pages outside `launchpad deploy` (git
+  integration / push-to-main); there's no platform-tracked manifest
+  to diff against.
+- **`live_drift_unknown`** — the app is live and tracked, but no
+  local `launchpad.yaml` exists to compare: status degrades to the
+  live-truth-only view (see below).
+- **`no deployed manifest yet`** — registered, but no deployed
+  manifest. Run `launchpad deploy` first.
+
+### Live build truth
+
+For every live state, status also renders the app's **last
+Cloudflare Pages deployment**: when it ran, what triggered it
+(`git push` vs `launchpad deploy (bot)`), the commit, and the build
+outcome — `build success`, `build IN PROGRESS`, or
+`build FAILED at stage "<stage>"` with a failure-log excerpt and
+what's still serving (the last successful deployment). This is the
+load-bearing answer to "my deploy exited 0 but the site didn't
+change": the commit can land while the asynchronous Pages build
+fails afterwards. Status also lists the app's **standing
+exceptions** (pre-existing, non-blocking policy violations already
+live on main — ADR 0025).
+
+### No local manifest? Status still works
+
+If `launchpad status` has a slug (explicit, or inferred from the
+directory name) but no local `launchpad.yaml`, it does **not**
+error (v0.26.1 behaviour): it degrades to the live-truth-only view —
+lifecycle + deployment block + standing exceptions, plus a one-line
+"drift not checked" note — and exits 0. In `--json` that view
+carries `"drift": null` and the `live_drift_unknown` state as the
+not-evaluated discriminant. A present-but-unreadable or invalid
+manifest is still a hard exit-2 error.
+
+### HEAD-vs-deployed surfacing
 
 Beyond drift, status also surfaces the relationship between the app
 repo's main HEAD sha and the last-applied manifest sha. If HEAD is
@@ -140,9 +200,14 @@ without polling tf-apply.
 
 ### Exit codes
 
-- **0** — in sync, OR drift in default (report-only) mode.
-- **1** — drift, when `--strict` is set.
-- **2** — error (missing local manifest, network, auth, etc.).
+- **0** — in sync, OR drift in default (report-only) mode, OR the
+  live-truth-only view (slug known, no local manifest).
+- **1** — drift, when `--strict` is set. With `--strict` and no
+  local manifest (drift can't be evaluated), exit 1 fires only when
+  the live build itself failed.
+- **2** — error (network, auth, unreadable/invalid local manifest).
+  A *missing* local manifest is no longer an error when the slug is
+  known — status degrades to the live-truth-only view instead.
 
 The default is report-only so casual interactive use never surprises
 the operator. For CI guards, use `--strict`:
@@ -176,10 +241,33 @@ launchpad status horizon --json
   "driftDetails": [
     { "path": "metadata.owner", "local": "alice@m-kopa.com", "deployed": "bob@m-kopa.com" },
     { "path": "production_env.API_BASE", "local": "https://new", "deployed": "https://old" }
-  ]
+  ],
+  "deployment": {
+    "slug": "horizon",
+    "supported": true,
+    "liveDeployment": {
+      "id": "<uuid>",
+      "createdOn": "<iso8601>",
+      "modifiedOn": "<iso8601>",
+      "url": "https://<id>.<project>.pages.dev",
+      "trigger": "bot",
+      "commit": { "hash": "<40-hex>", "message": "deploy via launchpad" },
+      "buildStatus": "success"
+    },
+    "lastSuccessfulDeployment": { "id": "<uuid>", "createdOn": "<iso8601>", "url": "..." }
+  }
 }
 ```
 
+Notes: JSON `state` values use underscores (`in_sync`, not
+`in sync`). Provisioning/failed states carry `stage` /
+`failedReason` / `submissionId` instead of the sha fields. The
+live-truth-only degrade adds `"drift": null`; on a failed build,
+`deployment.liveDeployment` carries `buildStatus: "failure"`,
+`failedStage`, and a `logExcerpt`. A `standingExceptions` array
+appears when the app has any. `deployment` is absent when the bot
+pre-dates the endpoint and `null` for apps with no Pages surface.
+
 ### production_env secret-shape warning
 
 If any `production_env.<KEY>` value matches a basic secret-shape
@@ -195,16 +283,16 @@ secrets bindings path. (This is informational; status will continue.)
 
 Warning, not block. If you see this: open `launchpad.yaml`, move the
 secret out of `production_env:` and into the `secrets:` bindings
-section (which gets written via `wrangler secret put`, never via
-git).
+section, then push the value with `launchpad secrets push` (the
+operator never runs `wrangler`; values never go via git).
 
 ## Common error patterns + fixes
 
 ### "session expired, run `launchpad login`"
 
-The Cf Access token is gone or stale. Run `launchpad login` once;
-both verbs work after that for the next ~24 hours (Cf Access session
-length).
+The session is gone or stale. Run `launchpad login` once; the session
+then stays fresh by silent refresh as you use the CLI — you'll only
+be asked to log in again after roughly a week of not using it.
 
 ### "not authorised for app X (you must be an owner or editor)"
 
@@ -227,6 +315,10 @@ launchpad apps             # confirm lifecycle is `live`
 /launchpad-deploy-status   # diagnose the M-892 stage trace
 ```
 
+If the record says `failed` but the app is actually serving,
+`launchpad recover <slug>` reconciles the record against live
+Cloudflare state (it verifies; it never fabricates a live state).
+
 ### "drift: hostnames[0]"
 
 The hostname changed in your local manifest but the deployed app
@@ -246,14 +338,16 @@ Group binding changed in your local manifest. This is the
 
 ## Related skills
 
-- **`/launchpad-deploy`** — provision a new app (uses `launchpad
-  create` not `deploy`; see skill for naming history).
+- **`/launchpad-deploy`** — provision a new app (`launchpad init`
+  to write the manifest, then `launchpad deploy`; the legacy
+  `launchpad create` wizard verb is deprecated).
 - **`/launchpad-deploy-status`** — interrogate provisioning state
   (M-892 stages). Use during initial provisioning; once the app is
   `live`, `launchpad status` is the daily-use tool.
-- **`/launchpad-content-pr`** — push first content to a freshly
-  provisioned app. After the first content lands, `launchpad
-  status` is how you check ongoing deploys.
+- **`/launchpad-content-pr`** — the iteration loop for a live app
+  (edit → deploy → verify). First content ships with the
+  provisioning run itself; after that, `launchpad status` is how
+  you check ongoing deploys.
 
 ## Anti-patterns