@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
@@ -0,0 +1,276 @@
1
+ ---
2
+ name: launchpad-integration-contract
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
5
+ ---
6
+
7
+ <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
8
+ ## Shell contract — read this first
9
+
10
+ Every fenced `bash` block below MUST be sent to the `Bash` tool **verbatim**.
11
+ Do not rewrite into PowerShell, cmd, zsh-isms, or "equivalent" forms.
12
+
13
+ - macOS / Linux: the `Bash` tool runs system bash.
14
+ - Windows: the `Bash` tool runs Git for Windows (MSYS) bash. `$HOME`,
15
+ forward slashes, `test -f`, `command -v`, heredocs, and `[[ … ]]` all
16
+ work. There is no reason to translate to `Test-Path`, `$env:USERPROFILE`,
17
+ `Get-Content`, `Where-Object`, `Get-ChildItem`, or backslash paths —
18
+ doing so will fail with `/usr/bin/bash: syntax error`.
19
+
20
+ If a step genuinely needs OS branching, branch *inside* bash:
21
+
22
+ ```bash
23
+ case "$(uname -s)" in
24
+ Darwin) : ;;
25
+ Linux) : ;;
26
+ MINGW*|MSYS*|CYGWIN*) : ;;
27
+ esac
28
+ ```
29
+ <!-- END shell-contract -->
30
+
31
+ # /launchpad-integration-contract
32
+
33
+ How to agree what an approved backend sends into a Launchpad app, before anyone builds the endpoint.
34
+
35
+ This is a **design** skill.
36
+ It produces three short documents: the payload contract, the allow-list request for the platform team, and the handoff note for the calling team.
37
+ `/launchpad-ingest` builds the endpoint afterwards.
38
+
39
+ ## How the pieces fit
40
+
41
+ - The **calling team** sends `Authorization: Bearer lpi_...` to one exact route on your app.
42
+ - The **gateway** checks the key, the route and the method against the platform's allow-list (`terraform/envs/prod/integrations.json`), and optionally the caller's IP.
43
+ On a match it strips the key and forwards a signed `X-Launchpad-Integration-Assertion`.
44
+ - **Your handler** verifies that assertion, validates the body and writes.
45
+
46
+ The contract is the part only you and the calling team can decide.
47
+ Everything else is mechanical.
48
+
49
+ ## Step 1 - start from the data you already have
50
+
51
+ Read the app's schema and the code that writes it today before proposing a single field.
52
+ If the machine data has to be counted, reported or exported next to what users enter by hand, write it into the **same table** with a column that says where each row came from.
53
+ A side table means every report, export and dashboard needs a second query, and someone forgets one.
54
+
55
+ Use a fresh table only when the machine data is a different kind of thing that no existing screen reads.
56
+ That is the case `/launchpad-ingest` scaffolds.
57
+
58
+ For an existing table, the change is additive:
59
+
60
+ ```sql
61
+ ALTER TABLE shelf_check ADD COLUMN idempotency_key TEXT;
62
+ ALTER TABLE shelf_check ADD COLUMN source TEXT;
63
+ CREATE UNIQUE INDEX IF NOT EXISTS shelf_check_idempotency_key ON shelf_check (idempotency_key);
64
+ ```
65
+
66
+ SQLite allows many `NULL`s under a unique index, so rows your users already wrote are untouched.
67
+ The insert then uses `ON CONFLICT(idempotency_key) DO NOTHING`.
68
+
69
+ ## Step 2 - split the fields: caller-set and server-set
70
+
71
+ Go through every column and put it in one of two lists.
72
+
73
+ **Server-set** fields come from the verified assertion or the server, never from the body:
74
+
75
+ - Who or what wrote the row (`source`, `checked_by`, `role`).
76
+ Set it from the verified integration name, for example `integration:routes-backend`.
77
+ - Received-at timestamps, row IDs, anything derived from your own lookups.
78
+
79
+ **Caller-set** fields are the facts only the caller knows: the item, who did it, when it happened, where.
80
+
81
+ If a field is used for attribution or permissions, it is server-set.
82
+ A body field is whatever the caller typed, so a caller-set `role: admin` is a bug waiting to happen.
83
+ This is the same rule the user path follows when it reads the user from `X-Launchpad-User-Assertion` instead of a form field.
84
+
85
+ ## Step 3 - pick the idempotency key
86
+
87
+ Every record carries an `idempotency_key`.
88
+ A retry with the same key returns `200` with `"duplicate": true` and writes nothing.
89
+
90
+ Choose with the calling team which of these it is, and write it down:
91
+
92
+ | Key | Use when | Effect |
93
+ |---|---|---|
94
+ | The caller's own record ID | The caller stores each event with a stable ID | Two genuine events about the same thing are two rows. |
95
+ | A natural key, such as `<sku>:<store_id>:<audit_week>` | There must only ever be one row per thing per period | A second, different event for the same thing is silently treated as a duplicate. |
96
+
97
+ The natural key is the one that bites.
98
+ If a driver can legitimately check the same shelf twice in a week, it drops the second check.
99
+ When unsure, use the caller's record ID and dedupe in reporting.
100
+
101
+ Never let the server generate the key.
102
+ The whole point is that the caller's retry sends the same value.
103
+
104
+ A key names one immutable record.
105
+ A resend with the same key and a different body is still answered as a duplicate, so the change is lost.
106
+ Tell the caller to send a correction under a new key, or agree a separate correction route.
107
+
108
+ ## Step 4 - business rules on the machine path
109
+
110
+ List every rule the user path enforces: submission windows, location limits, format checks, role checks.
111
+ For each one, decide whether the machine path follows it too, and what the caller sees.
112
+
113
+ The calling team is told to retry `429` and `5xx` and never retry other `4xx`, except where the contract names one.
114
+ So every refusal needs one of these, chosen on purpose:
115
+
116
+ - **`400`** for a body the caller must fix. Never retried.
117
+ - **`409`** with a clear `error` code for "valid, but not now", such as a closed audit week.
118
+ This is the one `4xx` a contract may name as resendable: never straight away, only once the condition has cleared and only if the handoff says so.
119
+ Spell out in the handoff when to resend (for example "hold it and resend once the next audit week opens") or that the record is dropped.
120
+ - **`200`** with a per-record status, when it is a batch and some records are refused.
121
+
122
+ Don't reuse `401` or `403` for business rules.
123
+ Those mean "wrong key" and "wrong integration or IP" to the caller and to whoever is on call.
124
+
125
+ ## Step 5 - shape the body
126
+
127
+ - **One record or a batch.** One record per request is the simplest contract and the default.
128
+ Ask for a batch only if the caller sends hundreds a minute.
129
+ The gateway rate-limits each integration and answers `429` above its ceiling.
130
+ A batch response must give a status per record, keyed by `idempotency_key`.
131
+ - **Timestamps** are ISO 8601 in UTC with a `Z`, for example `2026-10-07T09:00:00Z`.
132
+ If the table splits date and time into separate columns, the server does the split, so the caller sends one field.
133
+ - **Strict validation.** Reject unknown fields (`.strict()` in zod).
134
+ A typo then fails loudly instead of being dropped.
135
+ Give each field a type, a max length and a format where one exists.
136
+ - **No secrets and no more personal data than the app needs.** If the app doesn't show it, don't ask for it.
137
+ - **Name fields after your columns** where you can, so the handler is a straight copy.
138
+
139
+ ## Step 6 - versioning
140
+
141
+ The allow-list is exact: one host, one path, a fixed set of methods.
142
+ If you change the path or the methods in `launchpad.yaml`, the integration drops to `pending` and the gateway answers `401` until the platform approves the new values.
143
+
144
+ So:
145
+
146
+ - **Adding an optional field** is safe on the same route.
147
+ - **Removing a field, making one required, or changing its meaning** is a new route under a new integration name, such as `routes-backend-v2` on `/api/ingest/shelf-check-v2`.
148
+ Each integration has exactly one path and names are unique, so declare it next to the old one and get it approved with its own key.
149
+ Retire the old integration once the caller has moved.
150
+
151
+ ## Step 7 - the allow-list request
152
+
153
+ Send this to the platform team with `/launchpad-report`, once the contract is agreed:
154
+
155
+ ```text
156
+ App: <slug>.launchpad.m-kopa.us
157
+ Integration name: routes-backend
158
+ Path: /api/ingest/shelf-check
159
+ Methods: POST
160
+ Calling team: <team and a named contact>
161
+ Fixed egress IPs: <exact addresses, or "none">
162
+ Contract: <link to the agreed contract>
163
+ ```
164
+
165
+ The platform team adds the entry to `terraform/envs/prod/integrations.json` in a reviewed PR and mints the key.
166
+ The key goes straight to the calling team's secret store.
167
+ The app owner never holds it.
168
+
169
+ **IPs** are optional and must be exact IPv4 or IPv6 addresses.
170
+ CIDR ranges are refused.
171
+ With IPs set, a request from anywhere else gets `403 ip_not_allowed` even with the right key.
172
+ Ask the calling team early whether their outbound traffic leaves through fixed addresses, such as an Azure NAT gateway or firewall.
173
+ If it doesn't, skip the IP list rather than guessing.
174
+
175
+ ## Step 8 - the handoff note for the calling team
176
+
177
+ Keep it to one screen.
178
+ Never put a key in it.
179
+
180
+ ```text
181
+ Endpoint
182
+ POST https://<slug>.launchpad.m-kopa.us/api/ingest/shelf-check
183
+ Headers
184
+ Authorization: Bearer <key from your Key Vault>
185
+ Content-Type: application/json
186
+ Body
187
+ { "idempotency_key": "...", ...agreed fields... }
188
+ Unknown fields are refused. Timestamps are UTC ISO 8601.
189
+ idempotency_key
190
+ <what it is, from Step 3>. Send the same value on every retry.
191
+ Responses (one record per request; a batch route lists these per idempotency_key)
192
+ 200 {"ok":true,"duplicate":false} stored
193
+ 200 {"ok":true,"duplicate":true} already stored, nothing written
194
+ 400 bad body; the response lists the bad fields. Fix, don't retry.
195
+ 401 wrong key, path or method. Don't retry.
196
+ 403 wrong integration or IP not allowed. Don't retry.
197
+ 409 <your business-rule refusals, and whether to resend later or drop>
198
+ 429 / 5xx retry with exponential backoff and jitter.
199
+ Before go-live
200
+ Check your backend can reach *.launchpad.m-kopa.us from where it runs.
201
+ Tell us if outbound traffic uses fixed IPs.
202
+ ```
203
+
204
+ ## Step 9 - prove it live
205
+
206
+ Once the endpoint is deployed and approved, run each case against the real host.
207
+ The app owner never holds the key, so the calling team runs these (or a platform admin with a test key).
208
+ They share the response bodies with the key redacted, because checks 1 and 2 both return `200` and only the body shows `duplicate: false` then `duplicate: true`.
209
+ Fill in the values first; the block stops if any is missing.
210
+ `BODY` must be a valid record for your contract, with a fresh `idempotency_key` on every run.
211
+
212
+ ```bash
213
+ HOST="${HOST:?set HOST, for example https://<slug>.launchpad.m-kopa.us}"
214
+ ROUTE="${ROUTE:?set ROUTE, for example /api/ingest/shelf-check}"
215
+ KEY_FILE="${KEY_FILE:?set KEY_FILE to the path of the key file}"
216
+ BODY="${BODY:?set BODY to a valid test record with a fresh idempotency_key}"
217
+
218
+ # Only ever send the key to a Launchpad host over HTTPS.
219
+ case "$HOST" in
220
+ https://*/*|https://*@*|https://*:*) echo "HOST must be a bare https://<slug>.launchpad.m-kopa.us" >&2; exit 1 ;;
221
+ https://*.launchpad.m-kopa.us) : ;;
222
+ *) echo "HOST must be https://<slug>.launchpad.m-kopa.us" >&2; exit 1 ;;
223
+ esac
224
+
225
+ # The key goes in a 0600 header file so it never shows up in the process list,
226
+ # and the trap removes it even if a check fails or is interrupted.
227
+ AUTH="$(mktemp)"
228
+ trap 'rm -f "$AUTH"' EXIT
229
+ chmod 600 "$AUTH"
230
+ printf 'Authorization: Bearer %s\n' "$(cat "$KEY_FILE")" > "$AUTH"
231
+
232
+ # 1. stored: 200, duplicate false
233
+ curl -sS -X POST "$HOST$ROUTE" -H @"$AUTH" -H "Content-Type: application/json" -d "$BODY"
234
+ # 2. replay: 200, duplicate true
235
+ curl -sS -X POST "$HOST$ROUTE" -H @"$AUTH" -H "Content-Type: application/json" -d "$BODY"
236
+ # 3. bad body: 400, and the body lists the bad fields
237
+ curl -sS -w '\n%{http_code}\n' -X POST "$HOST$ROUTE" -H @"$AUTH" -H "Content-Type: application/json" -d '{}'
238
+ # 4. wrong path: 401
239
+ curl -sS -o /dev/null -w '%{http_code}\n' -X POST "$HOST$ROUTE-nope" -H @"$AUTH" -H "Content-Type: application/json" -d "$BODY"
240
+ ```
241
+
242
+ Delete the test rows afterwards, or agree a test SKU the app's reports ignore.
243
+
244
+ ## Worked example - shelf checks from delivery drivers
245
+
246
+ This app is made up.
247
+ `shelf-check` lets store staff record shelf checks in the browser, into `shelf_check`.
248
+ Delivery drivers also check shelves on their rounds, but they won't sign in to the app.
249
+ Their checks come from the drivers' mobile app, through the routing team's backend, into the same app.
250
+
251
+ - **Same table.** Driver checks must sit next to staff checks in every export, so they go into `shelf_check` with new `idempotency_key` and `source` columns (Step 1).
252
+ - **Server-set:** `source = integration:routes-backend`, `role = driver`, `checked_by = integration:routes-backend`.
253
+ - **Caller-set:** `sku`, `store_id`, `driver_id`, `audit_week`, `checked_at` (the server splits it into `check_date` and `check_time`), plus optional `gps` and `shelf_state`.
254
+ On the browser path the checker comes from the signed-in user.
255
+ Here the driver is not the caller, so `driver_id` is a body field the backend vouches for, and `checked_by` still records which integration sent it.
256
+ If the app keeps a driver roster, check `driver_id` against it and refuse unknown IDs with `400`.
257
+ - **Open questions for the owner:** whether a closed audit week refuses driver checks with `409 audit_week_closed` or accepts them late.
258
+ - **Key:** the routing backend's own check record ID, because a driver may check the same SKU twice in a week.
259
+
260
+ ## Checklist
261
+
262
+ - [ ] The contract names every field, says who sets it, and gives its type and format.
263
+ - [ ] Attribution and permission fields are server-set.
264
+ - [ ] The idempotency key is agreed and written down, with what a duplicate means.
265
+ - [ ] Every business rule has a status code and a retry instruction.
266
+ - [ ] The path is final. Changing it later means a new approval.
267
+ - [ ] The allow-list request is filed, with exact IPs or "none".
268
+ - [ ] The handoff note has no key in it.
269
+ - [ ] The four live checks pass against the real host.
270
+
271
+ ## Related
272
+
273
+ - `/launchpad-ingest` - build the verified endpoint once the contract is agreed.
274
+ - `/launchpad-report` - file the allow-list request.
275
+ - ADR 0060 - the trust model, approval by reviewed PR, and revoke latency.
276
+ - [Manifest reference: integrations](https://get.launchpad.m-kopa.us/manifest/#integrations-machine-callers).
@@ -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.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) -->
@@ -225,3 +225,23 @@ An older manifest with no origin set, for an unregistered static, React or React
225
225
  A new app with no origin set and KV, R2 or other unsupported wrangler bindings stops before deploying with the reason printed.
226
226
  An explicit `--origin pages` is available when required.
227
227
  Dispatch apps declare secrets as `secret_text` env vars and set them with `launchpad secrets push` once the first deploy has been delivered.
228
+
229
+ ## What changed in November 2026
230
+
231
+ - **Key-shaped literals now block a deploy.** `launchpad deploy` is refused
232
+ (HTTP 400 `secret_scan_violation`) when a file holds a literal that looks like
233
+ a key. The error names the file path and the rule, never the value. Seven
234
+ shape rules were added: `azure-client-secret`, `azure-storage-key`,
235
+ `anthropic-api-key`, `openai-api-key`, `stripe-live-key`, `google-api-key`
236
+ and `private-key-block` (they sit beside the older AWS, GitHub, Slack and SSH
237
+ / RSA / EC / PGP key rules). Fix: remove the literal from the file (if it was
238
+ real, rotate it), declare the name under `spec.env_vars` as `secret_text`, and
239
+ set the value with `launchpad secrets push`. Then run `launchpad deploy`
240
+ again; "Nothing to deploy - already live" just means the bundle matches what
241
+ is already live.
242
+ - **Personal data is not yet checked.** The platform does not yet block, warn
243
+ about or list files that hold personal data (for example a CSV with name,
244
+ email and phone columns): the detector is merged but switched off, so such a
245
+ file deploys without any message and stays in the app repo's history. The
246
+ owner must not deploy such files. Do not read the lack of a warning as
247
+ approval; ask before bundling any data file.
@@ -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.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) -->
@@ -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.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) -->
@@ -384,6 +384,13 @@ CI.
384
384
  - **Don't** rely on exit-1 firing without `--strict`. The default
385
385
  behaviour is report-only.
386
386
 
387
+ ## November 2026 change
388
+
389
+ Deploys are refused when a file holds a key-shaped literal, and files with
390
+ personal data are not yet checked by the platform: see `/launchpad-onboard`
391
+ § "What changed in November 2026". For a second deploy that stops with "no
392
+ trusted source baseline", see `/launchpad-content-pr`.
393
+
387
394
  ## Version
388
395
 
389
396
  This skill ships in launchpad-cli v0.56.0+.