@m-kopa/launchpad-cli 0.23.0

package/skills/launchpad-status/SKILL.md

@@ -0,0 +1,263 @@
+---
+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.23.0
+---
+
+<!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
+## Shell contract — read this first
+
+Every fenced `bash` block below MUST be sent to the `Bash` tool **verbatim**.
+Do not rewrite into PowerShell, cmd, zsh-isms, or "equivalent" forms.
+
+- macOS / Linux: the `Bash` tool runs system bash.
+- Windows: the `Bash` tool runs Git for Windows (MSYS) bash. `$HOME`,
+  forward slashes, `test -f`, `command -v`, heredocs, and `[[ … ]]` all
+  work. There is no reason to translate to `Test-Path`, `$env:USERPROFILE`,
+  `Get-Content`, `Where-Object`, `Get-ChildItem`, or backslash paths —
+  doing so will fail with `/usr/bin/bash: syntax error`.
+
+If a step genuinely needs OS branching, branch *inside* bash:
+
+```bash
+case "$(uname -s)" in
+  Darwin)               : ;;
+  Linux)                : ;;
+  MINGW*|MSYS*|CYGWIN*) : ;;
+esac
+```
+<!-- END shell-contract -->
+
+# /launchpad-status
+
+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.
+
+## When to use which verb
+
+- **`launchpad pull <slug>`** — read the deployed `launchpad.yaml`.
+  Use when you want to see what's actually running, or when you need
+  a starting point for editing a manifest.
+- **`launchpad status [<slug>] [--strict] [--json]`** — compare local
+  `./launchpad.yaml` against what's deployed and report drift. Use
+  before `launchpad deploy` to see what will change, or after to
+  confirm the change landed.
+
+If the operator is asking "did my deploy work" → `launchpad status`
+inside the app repo's clone is the answer.
+
+If they're asking "what was actually deployed" → `launchpad pull` is
+the answer.
+
+## Pre-flight
+
+Both verbs need a current Cf Access session. If `~/.launchpad/session.json`
+is missing or expired, surface the run-login hint:
+
+```bash
+launchpad whoami
+# If this fails: launchpad login
+```
+
+The app must exist in the registry (`launchpad apps` lists yours).
+Both verbs are owner/editor-scoped — non-members get HTTP 403 with
+"not authorised for app X (you must be an owner or editor)".
+
+## Slug resolution
+
+Both verbs accept the slug three ways, with this precedence:
+
+1. **`--slug <slug>`** — explicit, wins over everything.
+2. **Positional argument** — `launchpad pull horizon-clone`.
+3. **Current directory inference** — if cwd is named
+   `launchpad-app-<slug>/`, the slug is extracted automatically.
+   This is the default when you've `launchpad clone`d an app.
+
+`--file <path>` on `launchpad status` only changes which **local**
+manifest is read; it does NOT change slug resolution.
+
+## `launchpad pull`
+
+```bash
+# Write deployed launchpad.yaml to stdout
+launchpad pull horizon
+
+# Write to a file
+launchpad pull horizon --out /tmp/deployed.yaml
+
+# Inside an app-repo clone — slug inferred from cwd
+launchpad clone horizon
+cd launchpad-app-horizon
+launchpad pull
+```
+
+Exit codes:
+
+- **0** — manifest written successfully.
+- **1** — error (no deployed manifest yet, 401, 403, 404, network).
+
+## `launchpad status`
+
+Reads `./launchpad.yaml` by default, compares to the deployed
+manifest, reports state.
+
+### Three possible states
+
+- **`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).
+- **`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
+
+Beyond drift, status also surfaces the relationship between the app
+repo's main HEAD sha and the last-applied manifest sha. If HEAD is
+ahead of deployed:
+
+- With an open PR → "an apply may be queued (see PR #N)"
+- Without an open PR → "main is ahead of deployed"
+
+This is the load-bearing answer to "is my change going to land"
+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.).
+
+The default is report-only so casual interactive use never surprises
+the operator. For CI guards, use `--strict`:
+
+```bash
+# Interactive (default): show drift, exit 0
+launchpad status horizon
+
+# CI guard: fail the script if local differs from deployed
+launchpad status --strict horizon && launchpad deploy
+```
+
+### --json output
+
+For downstream scripts (M-1187 destroy, M-1189 update-skill, ad-hoc
+CI):
+
+```bash
+launchpad status horizon --json
+```
+
+```json
+{
+  "state": "drift",
+  "slug": "horizon",
+  "deployedSha": "<40-hex>",
+  "headSha": "<40-hex>",
+  "hasOpenPr": true,
+  "openPrNumber": 42,
+  "driftFields": ["metadata.owner", "production_env.API_BASE"],
+  "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" }
+  ]
+}
+```
+
+### production_env secret-shape warning
+
+If any `production_env.<KEY>` value matches a basic secret-shape
+heuristic — both a known prefix (`sk-`, `ghp_`, `gho_`, `ghu_`, `AKIA`,
+`xoxb-`, `xoxa-`, `xoxp-`) AND length ≥ 32 in a base64-shaped
+character set — status warns on stderr:
+
+```text
+launchpad status: production_env.OPENAI_KEY looks like a secret.
+production_env is non-secret by contract; move secrets to the
+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).
+
+## 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).
+
+### "not authorised for app X (you must be an owner or editor)"
+
+You're not on the app's `owner` or `editor` list, or in the
+break-glass admin group. Either:
+
+- Ask the app's current owner to add you as an editor via the portal
+  dashboard.
+- If you genuinely need break-glass access for this incident, talk to
+  platform-team.
+
+### "no deployed manifest for X yet"
+
+The app exists in the registry but `tf-apply` hasn't run yet (the
+first deploy may still be queuing) or the apply failed. Check:
+
+```bash
+launchpad apps             # confirm lifecycle is `live`
+# If lifecycle is `provisioning` or `failed`, use:
+/launchpad-deploy-status   # diagnose the M-892 stage trace
+```
+
+### "drift: hostnames[0]"
+
+The hostname changed in your local manifest but the deployed app
+still has the old hostname. This is a manifest-side change — run
+`launchpad deploy` to roll it out. (Hostname changes also require
+edge-auth + cert re-issuance — the gateway hostname/cert for an
+`auth: gateway` app, or the Cf Access app for an `auth: access` one —
+which the bot handles.)
+
+### "drift: access.allowed_entra_group"
+
+Group binding changed in your local manifest. This is the
+**load-bearing** drift — it controls who can access the app. After
+`launchpad deploy`, the resulting PR will require the
+`allowed-groups-change: true` label from a non-author human reviewer
+(AC-S4) before it can auto-merge.
+
+## Related skills
+
+- **`/launchpad-deploy`** — provision a new app (uses `launchpad
+  create` not `deploy`; see skill for naming history).
+- **`/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.
+
+## Anti-patterns
+
+- **Don't** try `--platform-repo /path/to/clone` — that flag was
+  removed in M-1188. Both verbs are bot-relayed; the operator never
+  needs a local platform-repo clone.
+- **Don't** parse the prose output of `launchpad status` in CI
+  scripts. Use `--json` and `--strict`.
+- **Don't** rely on exit-1 firing without `--strict`. The default
+  behaviour is report-only.
+
+## Version
+
+This skill ships in launchpad-cli v0.13.0+ (M-1188 release).

package/skills/marquee-share/README.md

@@ -0,0 +1,155 @@
+# marquee-share-skill
+
+A Claude Code skill that uploads an AI-chat HTML artefact to
+[Marquee](https://marquee.launchpad.m-kopa.us) `POST /api/uploads`,
+attributed to the **real signed-in user** (not a service token).
+
+This directory is a **self-contained Node program**, isolated from the
+Marquee Cloudflare Pages app at the repo root — it has its own
+`package.json`, `tsconfig.json`, ESLint and Vitest config. It is not
+part of the Pages build and does not deploy with the site.
+
+The skill runs from a **pre-built, dependency-free bundle**,
+`dist/cli.js`, which needs only Node 22+ — no `tsx`, no runtime
+`node_modules`. `dist/cli.js` is a **committed build artefact**
+(`npm run build` regenerates it). This matters because the skill is
+distributed by file-copy: the Launchpad CLI skills bundle copies
+`skill/` to `~/.claude/skills/marquee-share/` *without* `node_modules`,
+so the built bundle must be present in the tree.
+
+The skill is complete: a Claude Code [`SKILL.md`](./SKILL.md) drives a
+CLI that authenticates the user, wraps an AI-chat result in an
+M-KOPA-branded HTML document, uploads it, and returns a shareable
+`view_url`.
+
+## How it works
+
+A user says *"share this via Marquee"* in a Claude Code session.
+Claude renders the current result to an inner-content HTML fragment
+and runs the `share` command. The command wraps that fragment in the
+branded template, uploads the document to Marquee, and prints the
+`view_url`, which Claude returns to the user.
+
+```text
+Claude (renders content HTML)
+  └─ marquee-share share        src/cli.ts
+       ├─ renderBrandedDocument  src/render/template.ts   (M-KOPA shell)
+       ├─ getValidToken          src/auth/index.ts        (PKCE session)
+       └─ POST /api/uploads      src/upload/index.ts  →   view_url
+```
+
+## Install (personal)
+
+To use this skill in your own Claude Code, link it into your personal
+skills directory. Claude Code discovers skills by reading `SKILL.md`
+from each subdirectory of `~/.claude/skills/`; the install script
+symlinks `~/.claude/skills/marquee-share` at this `skill/` directory.
+
+```sh
+cd skill
+./install.sh        # symlink the skill into ~/.claude/skills/
+```
+
+No `npm install` is needed to *use* the skill — it runs from the
+committed, dependency-free `dist/cli.js` bundle. (`npm install` is only
+needed to *develop* the skill — see Development below.)
+
+`install.sh` is idempotent — re-running it is a no-op once the link is
+in place. Because it is a symlink, the skill you run always reflects
+this checkout: pull the branch and the skill updates with it. Restart
+Claude Code (or open a new session) to pick up the skill.
+
+To remove it:
+
+```sh
+cd skill
+./install.sh --uninstall
+```
+
+This is the **personal-developer** install path. M-KOPA-wide
+distribution goes through the Launchpad CLI skills bundle, which
+mirrors this directory as its canonical source.
+
+## CLI
+
+The skill ships a single command, `marquee-share`, with three
+subcommands. Run the built bundle from this directory:
+
+```sh
+node dist/cli.js login          # one-time browser sign-in
+node dist/cli.js logout         # clear the cached session
+node dist/cli.js share [file]   # wrap + upload; prints the view_url
+```
+
+`share` reads a complete inner-content HTML fragment from `[file]` or,
+when no file is given, from stdin. `--title "<text>"` sets the
+document title. On success it prints **only** the `view_url` to
+stdout; diagnostics go to stderr. On a first run with no session it
+triggers the browser login automatically, then proceeds. The bearer
+token is never printed or logged.
+
+`src/cli.ts` is the entrypoint source — a thin dispatcher that wires
+the auth and upload layers together. Its `run()` core takes every side
+effect as an injected dependency, so `tests/cli.test.ts` exercises it
+with fakes (no network, no browser, no real session file).
+
+`npm run build` bundles `src/cli.ts` and its imports into a single
+`dist/cli.js` with `bun build --target node`. The skill has zero
+runtime dependencies (auth and upload use only Node built-ins), so the
+bundle is fully self-contained. `dist/cli.js` carries a
+`#!/usr/bin/env node` shebang and is what the installed skill runs.
+
+Requires Node `>=22`. The shipped skill runs the built `dist/cli.js`
+under plain Node — no `tsx`, no `node_modules`. `tsx` is a
+devDependency, used only by the `typecheck`/`test` loop below.
+
+## Auth layer
+
+`src/auth/` is a vendored copy of the Launchpad CLI's Cloudflare
+Access Managed-OAuth / PKCE flow — see
+[`src/auth/PROVENANCE.md`](./src/auth/PROVENANCE.md) for the source
+commit and the Marquee-specific adaptations.
+
+The public surface is `src/auth/index.ts`:
+
+| Export | Purpose |
+|--------|---------|
+| `login()` | One-time interactive browser PKCE login; persists a session. |
+| `logout()` | Clears the cached session. |
+| `getValidToken()` | Returns a still-valid access token — reuses a cached session while fresh, silently refreshes on expiry, re-logins when the grant has expired. |
+
+### Security properties
+
+- **PKCE public client** — no client secret is generated, received,
+  or stored anywhere in the shipped skill.
+- **Session cached at `~/.marquee/session.json`, mode `0600`**;
+  parent dir `0700`. Override the path with `MARQUEE_SESSION_PATH`
+  (used by tests). Override the Marquee base URL with
+  `MARQUEE_RESOURCE_URL`.
+- **The credential is never logged, echoed, or committed.** The auth
+  layer prints only non-secret diagnostics (auth URLs, the session
+  file *path*). `tests/no-token-leak.test.ts` enforces this.
+- **No client-side JWT verification.** The skill is an OAuth client:
+  it presents the token; Marquee's Pages Functions verify it. (See
+  the repo's `ANTI-PATTERNS.md`.)
+
+## Development
+
+Developing the skill requires [**Bun**](https://bun.sh) installed on
+your `PATH` — `npm run build` invokes `bun build` to produce the
+dependency-free `dist/cli.js` bundle. Bun is a build-time prerequisite
+only; the shipped skill itself runs under plain Node 22+.
+
+```sh
+cd skill
+npm install
+npm run typecheck
+npm run lint
+npm test
+npm run build      # regenerate dist/cli.js — commit the result
+```
+
+`dist/cli.js` is a committed build artefact. Any change under `src/`
+must be followed by `npm run build`, and the regenerated `dist/cli.js`
+committed alongside the source change — the skill is distributed by
+file-copy, so a stale or missing bundle ships a stale or broken skill.

package/skills/marquee-share/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: marquee-share
+description: >-
+  Publish the current AI-chat result to Marquee as an M-KOPA-branded,
+  shareable web page and return its view URL. Use when the user says
+  "share this via Marquee", "share via marquee", "publish this to
+  Marquee", "put this on Marquee", or otherwise asks to share or
+  publish the current result as a Marquee link.
+---
+
+# Marquee share
+
+Turn the current chat result into a self-contained, M-KOPA-branded HTML
+page hosted on [Marquee](https://marquee.launchpad.m-kopa.us) and give
+the user back a shareable `view_url`. The page is attributed to the
+real signed-in user (Cloudflare Access), not a service account.
+
+## When to use
+
+Invoke when the user asks to share or publish the current result to
+Marquee — e.g. "share this via Marquee", "publish this to Marquee".
+
+## How to share
+
+All commands run from the `skill/` directory and invoke the bundled
+CLI directly with Node — `node dist/cli.js …`. `dist/cli.js` is a
+self-contained build that needs only Node 22+ on PATH; it has no
+runtime dependencies and does not require `npm install` or
+`node_modules/`.
+
+1. **Render the result to inner-content HTML.** Take whatever you just
+   produced for the user — prose, markdown, a code block, a table, a
+   short report — and write it out as clean, valid **HTML fragment**
+   (the inner body content only). Guidance:
+   - Headings → `<h2>`/`<h3>`; paragraphs → `<p>`; lists → `<ul>`/`<ol>`.
+   - Code → `<pre><code>…</code></pre>`; tables → real `<table>` markup.
+   - Escape any literal `<`, `>`, `&` that are meant as text.
+   - Write **only the content** — do **not** add `<html>`, `<head>`,
+     `<body>`, `<style>`, or `<script>`. Do **not** add your own
+     colours, fonts, or layout CSS.
+   - The white background and M-KOPA green/black branding are applied
+     for you by the skill's branded template — the `share` command
+     wraps your content in a complete, self-contained M-KOPA document.
+
+2. **Run the `share` command**, passing the HTML fragment on stdin and
+   a short human title:
+
+   ```sh
+   node dist/cli.js share --title "Quarterly summary" < content.html
+   ```
+
+   or pipe the HTML directly:
+
+   ```sh
+   printf '%s' "$CONTENT_HTML" | node dist/cli.js share --title "Quarterly summary"
+   ```
+
+   The `share` command prints **only** the resulting `view_url` to
+   stdout. Capture that single line.
+
+3. **Return the `view_url`** to the user as the shareable link. Do not
+   print anything else from the command's output as the result.
+
+## One-time browser sign-in
+
+The first time `share` runs on a machine with no Marquee session, it
+opens a browser for a one-time Cloudflare Access sign-in, then
+continues automatically — no separate step needed. The user can also
+sign in ahead of time:
+
+```sh
+node dist/cli.js login
+```
+
+The session is cached locally (`~/.marquee/session.json`, mode `0600`)
+and refreshed silently. The skill never prints or logs the token.
+
+To sign out:
+
+```sh
+node dist/cli.js logout
+```
+
+## Notes
+
+- Requires Node `>=22`. No `npm install` is needed to run the skill —
+  `dist/cli.js` is a pre-built, dependency-free bundle.
+- This skill is installed by symlinking `~/.claude/skills/marquee-share`
+  at the repo's `skill/` directory — see `skill/install.sh` and
+  `skill/README.md` for the install/uninstall steps.
+- `dist/cli.js` is a committed build artefact. After changing anything
+  under `src/`, regenerate it with `npm run build` in `skill/`.
+- If `share` exits non-zero, it prints a short `error: …` line on
+  stderr — report that to the user; do not retry blindly.

package/skills/marquee-share/SYNC.md

@@ -0,0 +1,27 @@
+# Vendored skill — DO NOT EDIT BY HAND
+
+This directory is a **mirror** of the `marquee-share` skill. Its
+canonical source is the `M-KOPA/marquee` repository, under `skill/`.
+
+It is vendored here so `launchpad skills install` can copy a working
+skill into `~/.claude/skills/` straight from the published
+`@m-kopa/launchpad-cli` npm package.
+
+## Provenance
+
+- source repo: `M-KOPA/marquee`
+- source path: `skill/`
+- source commit: `eb8261a621244667edc23d80850d5c39c1b54ee4`
+- synced by: `packages/launchpad-cli/scripts/sync-marquee-share-skill.sh`
+
+## Updating
+
+Do **not** edit files in this directory directly — changes will be
+overwritten and will drift from the canonical source. To pull a new
+version of the skill:
+
+```sh
+packages/launchpad-cli/scripts/sync-marquee-share-skill.sh <marquee-checkout> [ref]
+```
+
+then review the diff and commit. Run this at marquee-share release time.