@hailer/mcp 1.3.21 → 1.3.32

package/.claude/skills/create-and-publish-app/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: create-and-publish-app
-description: Scaffold, develop, and publish Hailer apps with @hailer/create-app — dev iteration, production publish, marketplace, validation, and cache gotchas
-version: 2.0.0
+description: Scaffold, develop, and publish Hailer apps with @hailer/create-app — load when scaffolding a new app, setting up dev iteration, publishing to production, or troubleshooting publish failures
+version: 2.5.0
 triggers:
   - create-app
   - npx create-app
@@ -31,14 +31,14 @@ npx @hailer/create-app <project-name> --template react-ts
 npx hailer-mcp prep-app <project-name>
 ```
 
-**Run `npx hailer-mcp prep-app <project-name>` immediately after scaffolding — it neutralizes the scaffold papercuts so you never hit them:** clears the placeholder `appId` (`65143728…`) and fake "Magic Apps Ltd." author from `public/manifest.json` (so first-publish detection is clean and no demo identity leaks), fixes the `StoreSet` `tsc` error in `src/hailer/use-app.ts`, writes a `.npmrc` with `include=dev` (so `npm install` pulls build deps even under Studio's `NODE_ENV=production` — which otherwise omits devDeps and breaks the build), and wires the `publish-*` scripts with `--env-file ../../.env` (per-project publish auth). Idempotent and safe to re-run. **`prep-app` writes `.npmrc` *after* `create-app`'s own install, so run `npm install --include=dev` once more after prep-app to pull the devDeps that first install skipped.** (Run prep-app from the SDK project root, where `npx hailer-mcp` resolves; pass the app dir or `apps/<name>`.)
+**Run `npx hailer-mcp prep-app <project-name>` immediately after scaffolding** — it neutralizes the scaffold's built-in papercuts: clears the placeholder `appId` (`65143728…`) and fake "Magic Apps Ltd." author from `public/manifest.json`, fixes the `StoreSet` tsc error in `src/hailer/use-app.ts`, writes a `.npmrc` with `include=dev` (so `npm install` pulls build deps even under `NODE_ENV=production`), and wires the `publish-*` scripts with `--env-file ../../.env` (per-project publish auth). Idempotent and safe to re-run. After prep-app, run `npm install --include=dev` once more to pull any devDeps that first install skipped.
 
 **This exact form is non-interactive — it runs with zero prompts. Do NOT deviate:**
-- **`<project-name>` is a POSITIONAL argument, not a flag.** `--name <x>` is silently ignored and the CLI drops to an interactive "Project name:" prompt that hangs an agent. Put the name first, bare.
-- **`--template` must be a real template name:** `react-ts` (recommended), `react`, `react-swc-ts`, `vanilla-ts`, `vanilla`, `preact-ts`, `preact`, `svelte-ts`, `svelte`. NOT `minimal` (invalid → drops to a "Select a framework" prompt that hangs).
-- **Use a fresh, lowercase, kebab-case name** in an empty target dir — that skips the overwrite prompt AND the package-name prompt. e.g. `injured-players-cost`.
-- Never run `npx @hailer/create-app` bare and never pipe input to it (`echo …|`, `printf`, `expect`) — the one-line form above already needs no input.
-- Run from a parent directory (`mkdir -p apps` first if needed), NEVER copy an existing app, then `cd <project-name> && npm install --include=dev` (the `--include=dev` survives `NODE_ENV=production`; the `.npmrc` prep-app writes makes later bare `npm install` safe too).
+- **`<project-name>` is a POSITIONAL argument, not a flag.** `--name <x>` is silently ignored and the CLI drops to an interactive "Project name:" prompt that hangs. Put the name first, bare.
+- **`--template react-ts` is the ONLY valid value** (`TEMPLATES = ['react-ts']`; all other frameworks are commented out). Any other name — `react`, `vanilla-ts`, `svelte`, `minimal` — drops to a "Select a framework" prompt that hangs.
+- **Use a fresh, lowercase, kebab-case name** in an empty target dir — that skips the overwrite prompt AND the package-name prompt.
+- Never run `npx @hailer/create-app` bare and never pipe input to it.
+- Run from a parent directory (`mkdir -p apps` first if needed), NEVER copy an existing app, then `cd <project-name> && npm install --include=dev`.
 </scaffold>
 
 <build>
@@ -53,8 +53,8 @@ Replace `src/App.tsx` and add components (load `hailer-app-builder` + `hailer-de
 - Apps must render outside Hailer too — empty state, never an error
 
 **Two scaffold facts that save a rabbit hole every build:**
-1. **The scaffold ships with ONE known `tsc` error** — `src/hailer/use-app.ts` types `StoreSet` `replace?: boolean`; it must be `replace?: false`. Fix that one line as your very first edit and tsc is clean. (Upstream create-app bug; not your code.)
-2. **Verify with `npm run build-production`, NOT `tsc` / `npm run build`.** `build-production` is vite-only — it's the exact command the publish runs. `npm run build` and `npx tsc --noEmit` run `tsc`, which trips on the scaffold error above and sends you chasing a problem the publish never sees. Verify the way you ship.
+1. **The scaffold ships with ONE known `tsc` error** — `src/hailer/use-app.ts` types `StoreSet` `replace?: boolean`; it must be `replace?: false`. Fix that one line first and tsc is clean.
+2. **Verify with `npm run build-production`, NOT `tsc` / `npm run build`.** `build-production` is vite-only — it's the exact command the publish runs. `npm run build` and `npx tsc --noEmit` run `tsc`, which trips on the scaffold error above.
 </build>
 
 <dev-publish>
@@ -79,25 +79,22 @@ After the first publish `public/manifest.json` holds the dev `appId`; later iter
 <credentials>
 ## Credentials — Read This Before Publishing Fails
 
-The publish CLI (`@hailer/app-sdk`'s `publish.cjs`, wrapped as `npm run publish-*`) resolves auth as: **`--user-api-key` flag → `USER_API_KEY` env → `HAILER_USER_API_KEY` env** (an API key and `--email` are mutually exclusive — passing one ignores the other). Those env vars are loaded by dotenv from **`--env-file <path>` first (if passed), then `~/.env`** in HOME; dotenv never overrides an already-set var, so the earlier source wins. Last resort: `--email` → interactive password prompt (useless for agents).
+The publish CLI (`@hailer/app-sdk`'s `publish.cjs`, wrapped as `npm run publish-*`) picks the API key as **`--user-api-key` flag → `USER_API_KEY` env → `HAILER_USER_API_KEY` env**. Those env vars are populated by dotenv from `--env-file` (loaded first) then `~/.env`; dotenv never overrides an already-set var, so a real env var wins, and `--env-file` wins over `~/.env`. (`--email` triggers interactive password auth instead — avoid it in agents.)
 
 - **Hailer Studio:** `~/.env` is auto-injected — publishing just works, no flags.
-- **Local machines:** the `npx hailer-mcp` server self-provisions on first boot — it mints a user API key from the project bot's credentials and writes `HAILER_USER_API_KEY` to the **project-root `.env`** (not `~/.env`). `prep-app` wires each app's `publish-*` script with `--env-file ../../.env`, so every project publishes to its own workspace. Once the local server has run once, publishing needs no auth flags. (Opt out: `HAILER_MCP_NO_PUBLISH_AUTH=true`.)
-- **⚠ Per-project, not machine-global.** Earlier versions wrote the key to `~/.env` — one slot shared by every project, so the last `npx hailer-mcp` to boot won it and other projects published to the WRONG workspace. Now each project's key lives in its own `.env` and `--env-file ../../.env` makes it win. Apps must live under `apps/<name>/` for that relative path to resolve; a top-level app needs re-homing under `apps/` or an explicit `-- --user-api-key <key>`.
-- **ALWAYS pass `-- --force`.** Without it the publish stops at an interactive `Overwrite the app? (Y/n)` prompt — which an agent cannot answer, so the command hangs until it times out. Every publish command below includes it; never drop it.
-- **If publishing still hits exit code 10** (no auth — the CLI prints usage and quits): the local server hasn't run yet, or injection was disabled. Start `npx hailer-mcp` once, OR ask the user for a Hailer user API key (Hailer → profile → API keys) and pass `-- --user-api-key <key>`. **Never read passwords from .env, never log in via curl, never probe API endpoints for keys.**
+- **Local machines:** `npx hailer-mcp` self-provisions on first boot — it mints a user API key from the project bot's credentials and writes `HAILER_USER_API_KEY` to the project-root `.env`. `prep-app` wires each app's `publish-*` script with `--env-file ../../.env`, so every project publishes to its own workspace. Once the local server has run once, publishing needs no auth flags.
+- **ALWAYS pass `-- --force`.** Without it the publish stops at an interactive `Overwrite the app? (Y/n)` prompt — which hangs indefinitely. `npm run publish-production -- --force` appends `--force` correctly; no manual `npm pack` step is needed.
+- **If publishing hits exit code 10** (no auth): start `npx hailer-mcp` once, OR ask the user for a Hailer user API key (Hailer → profile → API keys) and pass `-- --user-api-key <key>`.
 
-Other exit codes: 8 = login failed (bad key/credentials), 7 = bundle isn't a .tgz (build problem), loud version error = `--market` without `version`/`versionDescription` in the manifest.
+Other exit codes: 8 = login failed (bad key/credentials), 9 = upload/HTTP error, 7 = bundle isn't a .tgz (build problem), 2 = appId not found in this workspace, 6 = bad publish response. With `--create`: 11 = missing `--app-name`, 12 = missing `--workspace`, 13 = app-creation API call failed. 10 also fires on `--market` without `version`/`versionDescription` in the manifest.
 </credentials>
 
 <validate>
 ## Step 4 — Validate BEFORE Any Production Publish
 
-Check before publishing:
-
-1. Read `public/manifest.json`
-2. `appId` exists, 24 chars — required for any non-`--create` publish (auto-written by `--create`)
-3. `version` + `versionDescription` non-empty — strictly required for `--market` publishes (the CLI errors loudly without them); keep them set always, `versionDescription` doubles as the app description
+1. Read `public/manifest.json` (the source of truth; the publish actually reads the appId from the built `dist/manifest.json`, so edits to `public/` need a rebuild — `build-production` runs as part of `publish-*` — to take effect)
+2. `appId` exists, 24 chars — required for any non-`--create` publish
+3. `version` + `versionDescription` non-empty — strictly required for `--market` publishes
 4. `vite.config.ts` has `base: './'` — without it assets resolve to the root domain and production 403/404s while localhost works
 5. `index.html` has no-cache meta tags (apps.hailer.com is static hosting; server headers aren't controllable):
 
@@ -106,66 +103,56 @@ Check before publishing:
 <meta http-equiv="Pragma" content="no-cache" />
 <meta http-equiv="Expires" content="0" />
 ```
-
-If a publish reports success but the app still serves the old/localhost version, re-check 2–5 — historical silent failures trace back to these.
 </validate>
 
 <prod-publish>
 ## Step 5 — Production Publish (only when the user explicitly asks)
 
-**BEFORE any publish, run `npx hailer-mcp prep-app <name>`** (from the SDK project root; idempotent — safe to re-run, no-ops if already done). Apps scaffolded before the `--env-file` flag existed don't carry it in their `publish-*` scripts, so they'd authenticate from the machine-global `~/.env` and could publish to the WRONG workspace. Re-prepping retrofits `--env-file ../../.env` so this publish targets THIS project's workspace. This is the "prep on the fly" guard — touch an app to publish it, prep it first.
+**FIRST, decide first-publish vs update by READING `public/manifest.json` — never guess, never fail-first.**
 
-**THEN decide first-publish vs update by READING `public/manifest.json` — never guess, never fail-first.** The scaffold ships a placeholder `appId` of `65143728d2bd678b13daf289` (the "Magic Apps" demo). That value, or empty/missing, means this app has never been published:
+The scaffold ships a placeholder `appId` of `65143728d2bd678b13daf289` (the "Magic Apps" demo). That value, or empty/missing, means this app has never been published:
 
 | manifest `appId` | This is a… | Command |
 |---|---|---|
-| `65143728d2bd678b13daf289`, `""`, or missing | **FIRST publish** | `--create --app-name "<Name>" --workspace <wsId> --force` (all three required with `--create`) |
+| `65143728d2bd678b13daf289`, `""`, or missing | **FIRST publish** | `--create --app-name "<Name>" --workspace <wsId> --force` |
 | a real 24-char id you created earlier | **update** | `--force` only |
 
-A plain publish against the scaffold's placeholder appId silently uploads to the demo app (wrong) or errors — so on a fresh scaffold, ALWAYS take the `--create` path on the very first publish. Get `<wsId>` from `config.json` (`workspaceId`); derive `<Name>` from the project (e.g. "Upcoming Matches") or ask.
-
 ```bash
 # FIRST publish (fresh scaffold) — local machine
 npm run publish-production -- --create --app-name "<App Name>" --workspace <workspaceId> --force
 
-# FIRST publish — Hailer Studio (in-cluster; set --host to the public API explicitly)
+# FIRST publish — Hailer Studio
 npm run publish-production -- --host https://api.hailer.com --create --app-name "<App Name>" --workspace <workspaceId> --force
 
 # UPDATE (manifest already has a real appId)
 npm run publish-production -- --force
 ```
 
-**PUBLISH FAILURE PLAYBOOK — exact error → exact action, no improvising:**
+**PUBLISH FAILURE PLAYBOOK:**
 | Failure | Meaning | Action |
 |---|---|---|
-| exit 10, usage printed | no auth | start `npx hailer-mcp` once (mints the key), or `-- --user-api-key <key>` |
-| exit 2, "app was not found using <identity>" | manifest appId doesn't belong to this user/workspace (first publish, or a wrong appId) | re-run with **all three flags together — `--create` REQUIRES `--app-name "<Name>"` AND `--workspace <wsId>`** (`--create` alone, or with just `--force`, fails): `npm run publish-production -- --create --app-name "<Name>" --workspace <wsId> --force`. **NEVER "register the app first" via workspace/apps.ts** — that creates a registry entry with a URL you'd have to invent (placeholder URLs break the app: Hailer fetches `<url>/manifest.json` → "manifest missing"). `--create` makes the entry AND sets the real CDN URL |
-| exit 8 | login failed | the key/credentials are bad — re-mint or ask the user |
+| exit 10, usage printed | no auth | start `npx hailer-mcp` once, or pass `-- --user-api-key <key>` |
+| exit 2, "app was not found using…" | manifest appId doesn't belong to this workspace | re-run with `--create --app-name "<Name>" --workspace <wsId> --force` (all three required) |
+| exit 8 | login failed | bad key — re-mint or ask the user |
 | hangs at "Overwrite the app? (Y/n)" | missing `--force` | always pass it |
 
-**Manifest hand-edit rules:** never invent or copy an `appId` (only `--create` or a previous publish writes it); never delete `version`/`versionDescription` (versionDescription doubles as the app description, both are required for `--market`); do fix the placeholder `author` ("Magic Apps Ltd.") to the real one. apps.ts is for SHARING an app that already exists — after publish, `npm run pull` brings the entry in; edit members there.
-
 **FIRST-PUBLISH GOTCHA — the `--create` bundle embeds a stale manifest. Do these two things:**
-1. **Before publishing, fix `public/manifest.json`**: the scaffold leaves a placeholder `author` (e.g. "Magic Apps Ltd.") and `description`. Set the real values now — the agent controls these.
-2. **After the `--create` publish, republish once** (plain `npm run publish-production -- --force`). Reason: the script packs the tarball *before* `--create` learns the new `appId`, so the first uploaded bundle has the placeholder `appId` baked in. The second publish embeds the correct one (the manifest now holds the real `appId`). This is a known app-sdk ordering bug — the double-publish is the workaround, not optional.
-
-**What the CLI itself does** (`@hailer/app-sdk` publish.cjs): `--create` makes the app entry (`v3.app.create`) and writes the `appId` to the manifest; the bundle is packed (`package/` prefix) and POSTed to `/app/publish`; the server hosts it at `https://apps.hailer.com/{workspaceId}/{appId}/`.
+1. Before publishing, fix `public/manifest.json` placeholder `author` and `description`.
+2. After the `--create` publish, republish once (`npm run publish-production -- --force`). Reason: the script packs the tarball *before* `--create` learns the new `appId`, so the first uploaded bundle has the placeholder `appId` baked in. The second publish embeds the correct one.
 
-**What the CLI does NOT do:** icon, name/description updates, workspace sharing. Finish those after publishing: share with `manage_app({ action: 'add_member', appId, member: 'network_<wsId>' })`, and set an icon with `manage_app({ action: 'update', appId, image: <fileId> })` if wanted (icon files MUST be uploaded `isPublic: true`, PNG/JPEG only).
+**What the CLI does NOT do:** icon, name/description updates, workspace sharing. After publishing: share with `manage_app({ action: 'add_member', appId, member: 'network_<wsId>' })`, set icon with `manage_app({ action: 'update', appId, image: <fileId> })` (icon files MUST be uploaded `isPublic: true`, PNG/JPEG only).
 
 | Flag | Purpose |
 |------|---------|
-| `--create` | New app entry (clear/replace `appId` in manifest first if reusing a dev manifest) |
-| `--app-name` | Name shown in Hailer (required with `--create`) |
-| `--workspace` | Workspace ID (`config.json` at project root; required with `--create`) |
-| `--market` | Also publish this version to the marketplace (requires `version` + `versionDescription`; server returns `targetId`, auto-saved to manifest) |
+| `--create` | New app entry (requires `--app-name` AND `--workspace`) |
+| `--app-name` | Name shown in Hailer |
+| `--workspace` | Workspace ID (from `config.json` at project root) |
+| `--market` | Also publish to the marketplace (requires `version` + `versionDescription`) |
 | `--force` | Skip confirmation prompt |
-| `--host` | API URL override — required in cluster environments |
-| `--user-api-key` / `--email` | Explicit auth (mutually exclusive). Else `USER_API_KEY`/`HAILER_USER_API_KEY` env — loaded from `--env-file` then `~/.env` |
-| `--env-file <path>` | Load an env file before `~/.env` (wins on conflicts). `prep-app` sets `--env-file ../../.env` so each project publishes with its own key, not whatever last claimed `~/.env` |
-| `--production` / `--development` / `--staging` / `--local` | Environment preset (the `npm run publish-*` wrappers set these) |
-
-**Subsequent publishes:** just `npm run publish-production -- --force` (+ `--host` in Studio) — the manifest `appId` picks the target. Bump `version`/`versionDescription` per release.
+| `--host` | API URL override — required in Studio / cluster environments |
+| `--env-file <path>` | Load an env file before `~/.env` (wins on conflicts) |
+| `--user-api-key` | Explicit auth key |
+| `--production` / `--development` / `--staging` | Environment preset |
 
 **Environments:** `publish-production` → api.hailer.com, `publish-development` → testapi.hailer.biz, `publish-staging` → api.hailer.biz.
 
@@ -176,23 +163,24 @@ npm run publish-production -- --force
 ## Marketplace Publishing
 
 Two different things:
-1. **App version publish** (`npm run publish-production -- --market --force`) — uploads files AND registers the version on the marketplace. Requires `version` + `versionDescription` in the manifest; the server returns a `targetId`, auto-saved to `public/manifest.json`.
+1. **App version publish** (`npm run publish-production -- --market --force`) — uploads files AND registers the version on the marketplace. The server returns a `targetId`, auto-saved to `public/manifest.json`.
 2. **Marketplace listing** (MCP `publish_marketplace` with `type: 'app'`) — title, description, icon, images on the listing. Does NOT upload app files.
 
-First-time: publish with `--market` (get `targetId`) → `publish_marketplace({ type: 'app', appId, versionId: <targetId>, title, ... })` → note the returned `productId`. Metadata updates later use `productId`; new versions re-publish with `--market`.
+First-time: publish with `--market` (get `targetId`) → `publish_marketplace({ type: 'app', appId, versionId: <targetId>, title, ... })` → note the returned `productId`.
 
 | ID | What | Where |
 |----|------|-------|
 | `appId` | The app itself | manifest.json |
 | `targetId` | Version entry for marketplace | manifest.json (auto-saved) |
-| `productId` | Marketplace listing | returned by first `publish_marketplace`, find via `browse_marketplace` |
+| `productId` | Marketplace listing | returned by first `publish_marketplace` |
 </marketplace>
 
 <gotchas>
 ## Gotchas
 
-- **Icons must be uploaded `isPublic: true`** — private files render as broken/transparent images. The publish tool handles it; manual `upload_files` must pass the flag.
-- **No SVG icons** — the backend image pipeline (sharp) doesn't serve them; use PNG/JPEG. No SVG gradients in generated icons either (`flatten()` produces transparency — use solid RGB + composite).
+- **Icons must be uploaded `isPublic: true`** — private files render as broken/transparent images.
+- **No SVG icons** — the backend image pipeline (sharp) doesn't serve them; use PNG/JPEG.
 - **`StoreSet` type error** in scaffolded `src/hailer/use-app.ts`: `replace?: false`, not `boolean`.
-- Read the scaffolded project's README — it carries the exact commands for its version.
+- **Wrong-workspace key:** "The app was not found using: the provided API key" fires after auth succeeds — the key belongs to a different workspace. Primary fix: `npm run publish-production -- --env-file /absolute/path/to/project/.env --force`. `dotenv` loads `--env-file` before `~/.env` and strips surrounding double quotes itself.
+- **`@hailer/app-sdk` v1.0.3 publish bug:** v1's `publish.cjs` ignores `--user-api-key`, requires interactive password. Bump to `^2.5.0` + `npm install` to resolve.
 </gotchas>